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