SkyWalking Cross Process Propagation Headers Protocol

  • Version 3.0

SkyWalking is more akin to an APM system, rather than a common distributed tracing system. SkyWalking’s headers are much more complex than those found in a common distributed tracing system. The reason behind their complexity is for better analysis performance of the OAP. You can find many similar mechanisms in other commercial APM systems (some of which are even more complex than ours!).

Abstract

The SkyWalking Cross Process Propagation Headers Protocol v3, also known as the sw8 protocol, is designed for context propagation.

Standard Header Item

The standard header is the minimal requirement for context propagation.

  • Header Name: sw8.
  • Header Value: 8 fields split by -. The length of header value must be less than 2k (default).

Example of the value format: XXXXX-XXXXX-XXXX-XXXX

Values

Values must include the following segments, and all string type values are in BASE64 encoding.

  • Required:
  1. Sample. 0 or 1. 0 means that the context exists, but it could (and most likely will) be ignored. 1 means this trace needs to be sampled and sent to the backend. See Sampling for how the SkyWalking agents use this value.
  2. Trace ID. String(BASE64 encoded). A literal string that is globally unique.
  3. Parent trace segment ID. String(BASE64 encoded). A literal string that is globally unique.
  4. Parent span ID. Must be an integer. It begins with 0. This span ID points to the parent span in parent trace segment.
  5. Parent service. String(BASE64 encoded). Its length should be no more than 50 UTF-8 characters.
  6. Parent service instance. String(BASE64 encoded). Its length should be no more than 50 UTF-8 characters.
  7. Parent endpoint. String(BASE64 encoded). The operation name of the first entry span in the parent segment. Its length should be less than 150 UTF-8 characters.
  8. Target address of this request used on the client end. String(BASE64 encoded). The network address (not necessarily IP + port) used on the client end to access this target service.
  • Example value: 1-TRACEID-SEGMENTID-3-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORT

Sampling

SkyWalking analyzes the reported traces to provide complete metrics and topology, so it is common for the agents to sample 100% of the traces, which is their default. Storage is reduced instead by trace sampling at the server side, which drops traces without changing the metrics and topology. For this reason, the Sample value, designed at the beginning of this protocol, is not used in practice. By convention, the SkyWalking agent implementations always set Sample to 1 when they write the sw8 header, and don’t use it to decide whether to trace a request when they read the header.

When an agent supports sampling, the decision should be made once, by the service that starts the trace. An agent that receives a valid sw8 header should trace the request without applying its own sampling rate, so the upstream sampling decision is kept along the trace. The agent’s other rules still apply, such as ignored endpoints or suffixes, a disconnected backend, or a full buffer.

Extension Header Item

The extension header item is designed for advanced features. It provides interaction capabilities between the agents deployed in upstream and downstream services.

  • Header Name: sw8-x
  • Header Value: Split by -. The fields are extendable.

Values

The current value includes fields.

  1. Tracing Mode. Empty, 0, or 1. Empty or 0 is the default. 1 indicates that all spans generated in this context will skip analysis, spanObject#skipAnalysis=true. This context is propagated to upstream by default, unless it is changed in the tracing process.
  2. The timestamp of sending on the client end. This is used in async RPC, such as MQ. Once it is set, the consumer end would calculate the latency between sending and receiving, and tag the latency in the span by using key transmission.latency automatically.