From 6060464743da4ef021e540914ea3f7378341794c Mon Sep 17 00:00:00 2001 From: Wing <69376949+wingwong-knh@users.noreply.github.com> Date: Wed, 12 May 2021 19:57:10 +0800 Subject: [PATCH] Refine protocols (#6931) --- .../en/protocols/Browser-HTTP-API-Protocol.md | 12 ++-- docs/en/protocols/README.md | 57 +++++++++---------- 2 files changed, 32 insertions(+), 37 deletions(-) diff --git a/docs/en/protocols/Browser-HTTP-API-Protocol.md b/docs/en/protocols/Browser-HTTP-API-Protocol.md index 245711f52..72265e002 100644 --- a/docs/en/protocols/Browser-HTTP-API-Protocol.md +++ b/docs/en/protocols/Browser-HTTP-API-Protocol.md @@ -1,15 +1,15 @@ # HTTP API Protocol -HTTP API Protocol defines the API data format, including api request and response data format. +HTTP API Protocol defines the API data format, including API request and response data format. They use the HTTP1.1 wrapper of the official [SkyWalking Browser Protocol](Browser-Protocol.md). Read it for more details. ## Performance Data Report -Detail information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). +Detailed information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). ### POST http://localhost:12800/browser/perfData -Send a performance data object with JSON format. +Send a performance data object in JSON format. Input: @@ -41,11 +41,11 @@ Http Status: 204 ## Error Log Report -Detail information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). +Detailed information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). ### POST http://localhost:12800/browser/errorLogs -Send an error log object list with JSON format. +Send an error log object list in JSON format. Input: @@ -84,7 +84,7 @@ Http Status: 204 ### POST http://localhost:12800/browser/errorLog -Send a single error log object with JSON format. +Send a single error log object in JSON format. Input: diff --git a/docs/en/protocols/README.md b/docs/en/protocols/README.md index 42b917964..8dfd87d0c 100644 --- a/docs/en/protocols/README.md +++ b/docs/en/protocols/README.md @@ -1,48 +1,44 @@ # Protocols -There are two types of protocols list here. +There are two different types of protocols. -- [**Probe Protocol**](#probe-protocols). Include the descriptions and definitions about how agent send collected metrics data and traces, also the formats of each entities. +- [**Probe Protocol**](#probe-protocols). It includes descriptions and definitions on how agents send collected metrics data and traces, as well as the format of each entity. -- [**Query Protocol**](#query-protocol). The backend provide query capability to SkyWalking own UI and others. These queries are based on GraphQL. +- [**Query Protocol**](#query-protocol). The backend enables the query function in SkyWalking's own UI and other UIs. These queries are based on GraphQL. ## Probe Protocols -They also related to the probe group, for understand that, look [Concepts and Designs](../concepts-and-designs/overview.md) document. -These groups are **Language based native agent protocol**, **Service Mesh protocol** and **3rd-party instrument protocol**. +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**. -### Language based native agent protocol -There are two types of protocols to make language agents work in distributed environments. -1. **Cross Process Propagation Headers Protocol** and **Cross Process Correlation Headers Protocol** are in wire data format, -agent/SDK usually uses HTTP/MQ/HTTP2 headers -to carry the data with rpc request. The remote agent will receive this in the request handler, and bind the context -with this specific request. -1. **Trace Data Protocol** is out of wire data, agent/SDK uses this to send traces and metrics to skywalking or other -compatible backend. +### Language-based native agent protocol +There are two types of protocols that help language agents work in distributed environments. +1. **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. +1. **Trace Data Protocol** is in out-of-wire data format. Agent/SDK uses this to send traces and metrics to SkyWalking or other compatible backends. -[Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) is the new protocol for -in-wire context propagation, started in 8.0.0 release. +[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. -[Cross Process Correlation Headers Protocol v1](Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md) is a new in-wire context propagation additional and optional protocols. -Please read SkyWalking language agents documentations to see whether it is supported. +[Cross Process Correlation Headers Protocol v1](Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md) is a new in-wire context propagation protocol which is additional and optional. +Please read SkyWalking language agents documentation to see whether it is supported. This protocol defines the data format of transporting custom data with `Cross Process Propagation Headers Protocol`. -SkyWalking javaagent begins to support this since 8.0.0. +It has been supported by the SkyWalking javaagent since 8.0.0, -[SkyWalking Trace Data Protocol v3](Trace-Data-Protocol-v3.md) defines the communication way and format between agent and backend. +[SkyWalking Trace Data Protocol v3](Trace-Data-Protocol-v3.md) defines the communication method and format between the agent and backend. -[SkyWalking Log Data Protocol](Log-Data-Protocol.md) defines the communication way and format between agent and backend. +[SkyWalking Log Data Protocol](Log-Data-Protocol.md) defines the communication method and format between the agent and backend. ### Browser probe protocol -The browser probe, such as [skywalking-client-js](https://github.com/apache/skywalking-client-js) could use this protocol to send to backend. This service provided by gRPC. +The browser probe, such as [skywalking-client-js](https://github.com/apache/skywalking-client-js), could use this protocol to send data to the backend. This service is provided by gRPC. -[SkyWalking Browser Protocol](Browser-Protocol.md) define the communication way and format between `skywalking-client-js` and backend. +[SkyWalking Browser Protocol](Browser-Protocol.md) defines the communication method and format between `skywalking-client-js` and backend. ### Service Mesh probe protocol -The probe in sidecar or proxy could use this protocol to send data to backendEnd. This service provided by gRPC, requires -the following key info: +The probe in sidecar or proxy could use this protocol to send data to the backend. This service provided by gRPC requires +the following key information: -1. Service Name or ID at both sides. -1. Service Instance Name or ID at both sides. +1. Service Name or ID on both sides. +1. Service Instance Name or ID on both sides. 1. Endpoint. URI in HTTP, service method full signature in gRPC. 1. Latency. In milliseconds. 1. Response code in HTTP @@ -52,14 +48,13 @@ the following key info: ### Events Report Protocol -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 messages formats of events. +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. ### 3rd-party instrument protocol -3rd-party instrument protocols are not defined by SkyWalking. They are just protocols/formats, which SkyWalking is compatible and -could receive from their existed libraries. SkyWalking starts with supporting Zipkin v1, v2 data formats. +3rd-party instrument protocols are not defined by SkyWalking. They are just protocols/formats with which SkyWalking is compatible, and SkyWalking could receive them from their existing libraries. SkyWalking starts with supporting Zipkin v1, v2 data formats. -Backend is based on modularization principle, so very easy to extend a new receiver to support new protocol/format. +The backend has a modular design, so it is very easy to extend a new receiver to support a new protocol/format. ## Query Protocol -Query protocol follows GraphQL grammar, provides data query capabilities, which depends on your analysis metrics. +The query protocol follows GraphQL grammar, and provides data query capabilities, which depends on your analysis metrics. Read [query protocol doc](query-protocol.md) for more details.