diff --git a/docs/en/protocols/README.md b/docs/en/protocols/README.md index 7b6b7ee29ce98e6486fa09a5927580d7095e9727..412dfbc73e894e1bc34c6a8ffe705baa32fe5b42 100644 --- a/docs/en/protocols/README.md +++ b/docs/en/protocols/README.md @@ -1,15 +1,10 @@ -# Probe Protocol -It includes descriptions and definitions on how agents send collected metrics, logs, traces and events, as well as the format of each entity. - -## Probe Protocols -They also related to the probe group. For more information, see [Concepts and Designs](../concepts-and-designs/overview.md). -These groups are **language-based native agent protocol**, **service mesh protocol** and **3rd-party instrument protocol**. +# Probe Protocols +Probe protocols describe and define how agents send collected metrics, logs, traces, and events, as well as set out the format of each entity. ### Tracing There are two types of protocols that help language agents work in distributed tracing. -- **Cross Process Propagation Headers Protocol** and **Cross Process Correlation Headers Protocol** come in in-wire data format. Agent/SDK usually uses HTTP/MQ/HTTP2 headers -to carry the data with the RPC request. The remote agent will receive this in the request handler, and bind the context with this specific request. +- **Cross Process Propagation Headers Protocol** and **Cross Process Correlation Headers Protocol** come in in-wire data format. Agent/SDK usually uses HTTP/MQ/HTTP2 headers to carry the data with the RPC request. The remote agent will receive this in the request handler, and bind the context with this specific request. [Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) has been the new protocol for in-wire context propagation since the version 8.0.0 release. @@ -26,14 +21,14 @@ Please read SkyWalking language agents documentation to see whether it is suppor ### Metrics -SkyWalking has native metrics format, and support widely used metric formats such as Prometheus, OpenCensus, and Zabbix. +SkyWalking has a native metrics format, and supports widely used metric formats, such as Prometheus, OpenCensus, and Zabbix. The native metrics format definition could be found [here](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Meter.proto). -Typically, agent meter plugin(e.g. [Java Meter Plugin](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/java-plugin-development-guide/#meter-plugin)) and +Typically, the agent meter plugin (e.g. [Java Meter Plugin](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/java-plugin-development-guide/#meter-plugin)) and Satellite [Prometheus fetcher](https://skywalking.apache.org/docs/skywalking-satellite/latest/en/setup/plugins/fetcher_prometheus-metrics-fetcher/) -would transfer metrics into native format and forward to SkyWalking OAP server. +would convert metrics into native format and forward them to SkyWalking OAP server. -About receiving 3rd party formats metrics, read [Meter receiver](../setup/backend/backend-meter.md) and [OpenTelemetry receiver](../setup/backend/opentelemetry-receiver.md) docs for more details. +To learn more about receiving 3rd party formats metrics, see [Meter receiver](../setup/backend/backend-meter.md) and [OpenTelemetry receiver](../setup/backend/opentelemetry-receiver.md). ### Browser probe protocol @@ -45,8 +40,8 @@ The browser probe, such as [skywalking-client-js](https://github.com/apache/sky The protocol is used to report events to the backend. The [doc](../concepts-and-designs/event.md) introduces the definition of an event, and [the protocol repository](https://github.com/apache/skywalking-data-collect-protocol/blob/master/event) defines gRPC services and message formats of events. -Report `JSON` format events via HTTP API, the endpoint is `http://:12800/v3/events`. -JSON event record example: +`JSON` format events can be reported via HTTP API. The endpoint is `http://:12800/v3/events`. +Example of a JSON event record: ```json [ { diff --git a/docs/en/protocols/Trace-Data-Protocol-v3.md b/docs/en/protocols/Trace-Data-Protocol-v3.md index 355b0c60d4b5cfc263aed21d8c65b6a6554725b9..df20124fcd85555b27305ac7d1f26ca180e68e53 100644 --- a/docs/en/protocols/Trace-Data-Protocol-v3.md +++ b/docs/en/protocols/Trace-Data-Protocol-v3.md @@ -2,13 +2,11 @@ Trace Data Protocol describes the data format between SkyWalking agent/sniffer and backend. ## Overview -Trace data protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol), -also implemented in [HTTP 1.1](HTTP-API-Protocol.md) +Trace data protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol), and implemented in [HTTP 1.1](HTTP-API-Protocol.md). ### Report service instance status 1. Service Instance Properties -Service instance contains more information than just a name. Once the agent wants to report this, use `ManagementService#reportInstanceProperties` service -to provide a string-key/string-value pair list as the parameter. `language` of target instance is expected at least. +Service instance contains more information than just a name. In order for the agent to report service instance status, use `ManagementService#reportInstanceProperties` service to provide a string-key/string-value pair list as the parameter. The `language` of target instance must be provided as the minimum requirement. 2. Service Ping Service instance should keep alive with the backend. The agent should set a scheduler using `ManagementService#keepAlive` service every minute. @@ -17,7 +15,7 @@ Service instance should keep alive with the backend. The agent should set a sche After you have the service ID and service instance ID ready, you could send traces and metrics. Now we have 1. `TraceSegmentReportService#collect` for the SkyWalking native trace format -1. `JVMMetricReportService#collect` for the SkyWalking native jvm format +1. `JVMMetricReportService#collect` for the SkyWalking native JVM format For trace format, note that: 1. The segment is a unique concept in SkyWalking. It should include all spans for each request in a single OS process, which is usually a single language-based thread. diff --git a/docs/en/protocols/query-protocol.md b/docs/en/protocols/query-protocol.md index ba188f5a7a32d1ad97f48586521bd6a2d36ad355..62ae902c6ac9e1a258d7178e26d0162557cd2401 100644 --- a/docs/en/protocols/query-protocol.md +++ b/docs/en/protocols/query-protocol.md @@ -139,10 +139,10 @@ extend type Query { } ``` -Log implementations have a little differences with different database options. Search engine(s), e.g. ElasticSearch and OpenSearch, could support -full log text fuzzy query. Others would not support considering performance impact and end user experience. +Log implementations vary between different database options. Some search engines like ElasticSearch and OpenSearch can support +full log text fuzzy queries, while others do not due to considerations related to performance impact and end user experience. -`test` API is provided for the debugger tool of native LAL parsing. +`test` API serves as the debugging tool for native LAL parsing. ### Trace ```graphql @@ -152,7 +152,7 @@ extend type Query { } ``` -Trace query provides to fetch trace segment list, and spans of given trace id. +Trace query fetches trace segment lists and spans of given trace IDs. ### Alarm ```graphql @@ -162,7 +162,7 @@ extend type Query { } ``` -Alarm query provides to query detected alerting messages with relative events. +Alarm query identifies alarms and related events. ### Event ```graphql @@ -171,7 +171,7 @@ extend type Query { } ``` -Event query is fetching the event list according to given sources and time range conditions. +Event query fetches the event list based on given sources and time range conditions. ## Condition ### Duration