This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking.git


The following commit(s) were added to refs/heads/master by this push:
     new 76847db  Refine protocols doc (#8049)
76847db is described below

commit 76847db783653c7e906a296108e2588b583e5678
Author: Wing <[email protected]>
AuthorDate: Tue Nov 2 01:49:36 2021 -0700

    Refine protocols doc (#8049)
---
 docs/en/protocols/README.md                 | 23 +++++++++--------------
 docs/en/protocols/Trace-Data-Protocol-v3.md |  8 +++-----
 docs/en/protocols/query-protocol.md         | 12 ++++++------
 3 files changed, 18 insertions(+), 25 deletions(-)

diff --git a/docs/en/protocols/README.md b/docs/en/protocols/README.md
index 7b6b7ee..412dfbc 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://<oap-address>:12800/v3/events`.
-JSON event record example:
+`JSON` format events can be reported via HTTP API. The endpoint is 
`http://<oap-address>: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 355b0c6..df20124 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 ba188f5..62ae902 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

Reply via email to