diff --git a/docs/en/protocols/README.md b/docs/en/protocols/README.md index 8a6d55531235..2392d5ee1bbb 100644 --- a/docs/en/protocols/README.md +++ b/docs/en/protocols/README.md @@ -22,7 +22,9 @@ service ID. ### Language based native agent protocol This protocol is combined from two parts: -* [Cross Process Propagation Headers Protocol](Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md) is for in-wire propagation. +* [**SW6** Cross Process Propagation Headers Protocol](Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md) is the new protocol for +in-wire context propagation, started in 6.0.0-beta release. It will replace the old **SW3** protocol in the future, now both of them are supported. +* [**SW3** Cross Process Propagation Headers Protocol](Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md) is for in-wire propagation. By following this protocol, the trace segments in different processes could be linked. * [SkyWalking Trace Data Protocol](Trace-Data-Protocol.md) define the communication way and format between agent and backend. diff --git a/docs/en/protocols/Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md b/docs/en/protocols/Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md new file mode 100644 index 000000000000..e24a09e73e27 --- /dev/null +++ b/docs/en/protocols/Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md @@ -0,0 +1,43 @@ +# SkyWalking Cross Process Propagation Headers Protocol +* Version 2.0 + +## Abstract +SkyWalking Cross Process Propagation Headers Protocol v2 is also named as sw6 protocol. This protocol keeps the same purposes +of [v1(a.k.a. sw3)](Skywalking-Cross-Process-Propagation-Headers-Protocol-v1.md), which is keep context propagation works. + +## Differences from v1 +The major differences of v2 and v1, comes from SkyWalking's evolution, including +1. Mesh and languages are not same always, some info in headers should be optional. +1. BASE64 encoding required. +1. Sampling flag is including. + +## Header Item +* Header Name: `sw6` +* Header Value: Split by `-`, the parts are following. The length of header value should be less than 2k(default). + +Value format example, `XXXXX-XXXXX-XXXX-XXXX` + +## Values +Values include the following segments, all String type values are in BASE64 encoding. + +- Required(s) +1. Sample. 0 or 1. 0 means context exists, but could(most likely will) ignore. 1 means this trace need to be sampled and send to backend. +1. Trace Id. **String(BASE64 encoded)**. Three Longs split by `.` to represent the unique id of this trace. +1. Parent trace segment Id. **String(BASE64 encoded)**. Three Longs split by `.` to represent the unique id of parent segment in parent service. +1. Parent span Id. Integer. Begin with 0. This span id points to the parent span in parent trace segment. +1. Parent service instance Id. Integer. The instance ID of parent service. +1. Entrance service instance Id. Integer. The instance ID of the entrance service. +1. Target address of this request. **String(BASE64 encoded)**. The network address(not must be IP + port) used at client side to access this target +service. _This value can use exchange/compress collector service to get the id(integer) to represent the string. If you use the string, it must start with `#`, others use integer directly._ + +- Optional(s) + +Optional values could not exist if the agent/SDK haven't those info or the length of header is over the threshold(2k default). +1. Entry endpoint of the trace. **String(BASE64 encoded)**. +_This value can use exchange/compress collector service to get the id(integer) to represent the string. If you use the string, it must start with `#`, others use integer directly._ +1. Parent endpoint of the parent service. **String(BASE64 encoded)**. +_This value can use exchange/compress collector service to get the id(integer) to represent the string. If you use the string, it must start with `#`, others use integer directly._ + +## Sample values +1. Short version, `1-TRACEID-SEGMENTID-3-5-2-IPPORT` +1. Complete version, `1-TRACEID-SEGMENTID-3-5-2-IPPORT-PARENTURI-ENTRYURI` \ No newline at end of file