From 919c8af37763495a3d8605b3a45b47fb69ea280f Mon Sep 17 00:00:00 2001 From: mrproliu <741550557@qq.com> Date: Thu, 19 Mar 2020 11:39:44 +0800 Subject: [PATCH] SkyWalking Cross Process Correlation Headers Protocol (#4509) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * provide the data transmission protocol Co-authored-by: Mrproliu Co-authored-by: 吴晟 Wu Sheng Co-authored-by: kezhenxu94 Co-authored-by: zhang-wei --- docs/en/protocols/README.md | 17 ++++++----------- ...s-Process-Correlation-Headers-Protocol-v1.md | 16 ++++++++++++++++ 2 files changed, 22 insertions(+), 11 deletions(-) create mode 100644 docs/en/protocols/Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md diff --git a/docs/en/protocols/README.md b/docs/en/protocols/README.md index dda0c8e8b7..d1f5bb4e63 100644 --- a/docs/en/protocols/README.md +++ b/docs/en/protocols/README.md @@ -10,15 +10,9 @@ There are two types of protocols list here. They also related to the probe group, for understand that, look [Concepts and Designs](../concepts-and-designs/README.md) document. These groups are **Language based native agent protocol**, **Service Mesh protocol** and **3rd-party instrument protocol**. -## Register Protocol -Include service, service instance, network address and endpoint meta data register. -Purposes of register are -1. For service, network address and endpoint, register returns the unique ID of register object, usually an integer. Probe -can use that to represent the literal String for data compression. Further, some protocols accept IDs only. -1. For service instance, register returns a new unique ID for every new instance. Every service instance register must contain the -service ID. - - +### Register Protocol +Register protocol is shared in `Language based native agent protocol`[Required] and `Service Mesh probe protocol`[Optional]. +Service, Service Instance, Network address and Endpoint could do register to get an unique integer ID to replace the literal string name and attributes. The probe could use IDs to reduce the cost of memory and network bandwidth. Service and Instance register are required in the language agent. All other cases, register are optional. ### Language based native agent protocol There is two types of protocols to make language agents work in distributed environments. @@ -29,11 +23,12 @@ with this specific request. compatible backend. [Cross Process Propagation Headers Protocol v2](Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md) is the new protocol for -in-wire context propagation, started in 6.0.0-beta release, older protocol is no longer supported. +in-wire context propagation, started in 6.0.0-beta release, v1 is no longer supported. Since SkyWalking v6.0.0-beta, SkyWalking agent and backend are using Trace Data Protocol v2. -[SkyWalking Trace Data Protocol v2](Trace-Data-Protocol-v2.md) define the communication way and format between agent and backend. +[SkyWalking Trace Data Protocol v2](Trace-Data-Protocol-v2.md) defines the communication way and format between agent and backend. +* [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. This protocol defines the data format of transporting custom data with `Cross Process Propagation Headers Protocol v2`. SkyWalking javaagent begins to support this since 7.1.0. ### 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 diff --git a/docs/en/protocols/Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md b/docs/en/protocols/Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md new file mode 100644 index 0000000000..211c15ad67 --- /dev/null +++ b/docs/en/protocols/Skywalking-Cross-Process-Correlation-Headers-Protocol-v1.md @@ -0,0 +1,16 @@ +# SkyWalking Cross Process Correlation Headers Protocol +* Version 1.0 + +The Cross Process Correlation Headers Protocol is used to transport custom data by leveraging the capability of [Cross Process Propagation Headers Protocol](Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md). + +This is an optional and additional protocol for language tracer implementation. All tracer implementation could consider to implement this. +Cross Process Correlation Header key is `sw7-correlation`. The value is the `encoded(key):encoded(value)` list with elements splitted by `,` such as `base64(string key):base64(string value),base64(string key2):base64(string value2)`. + +## Recommendations of language APIs +Recommended implementation in different language API. + +1. `CorrelationContext#set` and `CorrelationContext#get` are recommended to write and read the correlation context, with key/value string. +1. The key should be added if it is absent. +1. The later writes should override the previous value. +1. The total number of all keys should be less than 3, and the length of each value should be less than 128 bytes. +1. The context should be propagated as well when tracing context is propagated across threads and processes. -- GitLab