Trace context propagation passes tracing metadata -- trace IDs, span IDs, and sampling decisions -- between services in a distributed application. This allows all spans within a request to be correlated into a single end-to-end trace.
Application Real-Time Monitoring Service (ARMS) supports five trace propagation protocols.
| Protocol | Type | Header prefix |
|---|---|---|
| EagleEye | Alibaba Cloud proprietary | EagleEye- |
| W3C Trace Context | W3C standard | traceparent, tracestate |
| Zipkin (B3) | Open source | X-B3- |
| Jaeger | Open source | uber-trace-id |
| SkyWalking | Open source | sw8 |
EagleEye protocol
EagleEye is an Alibaba Cloud proprietary protocol developed by ARMS and widely used across Alibaba Cloud services.
Header fields
| Header | Description | Example |
|---|---|---|
EagleEye-TraceID | Trace identifier (random 32-bit string). | -- |
EagleEye-RpcID | Hierarchical span relationship. 0 is the parent span; 0.1 and 0.2 are child spans of 0; 0.1.1 is a child of 0.1. | 0, 0.1, 0.2, 0.1.1 |
EagleEye-SpanID | Span identifier (random long integer). Compatible with open-source redundant fields. | -- |
EagleEye-pSpanID | Parent span identifier (random long integer). Compatible with open-source redundant fields. | -- |
EagleEye-Sampled | Sampling flag. | -- |
EagleEye-pAppName | Upstream application name. | -- |
EagleEye-pRpc | Upstream application interface. | -- |
EagleEye-UserData | Baggage data propagated with the trace. | k1=v1&k2=v2 |
W3C Trace Context protocol
The W3C Trace Context specification is a vendor-neutral standard defined by the World Wide Web Consortium (W3C).
Header fields
| Header | Format | Example |
|---|---|---|
traceparent | <version>-<trace-id>-<parent-span-id>-<Sampling identifier> (2-bit version, 32-bit trace ID, 16-bit parent span ID, sampling identifier) | 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 |
tracestate | Baggage data propagated with the trace. | k1=v1&k2=v2 |
Zipkin (B3) protocol
The B3 propagation format is used by Zipkin.
Header fields
| Header | Description | Example |
|---|---|---|
X-B3-TraceId | 32-bit trace identifier. | 0af7651916cd43dd8448eb211c80319c |
X-B3-SpanId | 16-bit span identifier. | b7ad6b7169203331 |
X-B3-ParentSpanId | 16-bit parent span identifier. | b7ad6b7169203331 |
X-B3-Sampled | Sampling flag. 1 = sampled, 0 = not sampled. | 1 |
baggage- | Baggage data prefix. Append the key name after the prefix. | baggage-k1=v1, baggage-k2=v2 |
Jaeger protocol
The Jaeger propagation format is used by Jaeger.
Header fields
| Header | Format | Example |
|---|---|---|
uber-trace-id | <trace-id>:<span-id>:<parent-span-id>:<flags> | 0af7651916cd43dd8448eb211c80319c:b7ad6b7169203331:b7ad6b7169203331:1 |
uberctx- | Baggage data prefix. Append the key name after the prefix. | uberctx-k1=v1, uberctx-k2=v2 |
SkyWalking protocol
The SkyWalking propagation format is used by Apache SkyWalking.
sw8 header
The sw8 header consists of eight hyphen-separated fields. All string values must be Base64-encoded. The total header length must be less than 2,000 characters.
| Field | Position | Description |
|---|---|---|
| Sample | 1 | 0 = context exists but can be ignored. 1 = sample and send to backend. |
| Trace ID | 2 | Unique trace identifier. Base64-encoded string of three long values separated by periods (.). |
| Parent trace segment ID | 3 | Globally unique segment identifier. Base64-encoded string. |
| Parent span ID | 4 | 0 or a positive integer. |
| Parent service | 5 | Base64-encoded string. Must exceed 50 UTF-8 characters. |
| Parent service instance ID | 6 | Base64-encoded string. Must exceed 50 UTF-8 characters. |
| Parent service endpoint | 7 | Endpoint of the first entry span in the parent trace segment. Base64-encoded string. Must exceed 50 UTF-8 characters. |
| Destination URL | 8 | URL of the destination service. Format may differ from <IP address><Port number>. Base64-encoded string. |
Example:
1-TRACEID-SEGMENTID-3-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORTsw8-x header
The sw8-x header carries extension fields, also separated by hyphens. Fields can be extended as needed.
The tracking mode accepts null, 0, or 1:
nullor0(default): All spans generated in the current context are not analyzed. Context is propagated upstream by default unless changed during tracking.1: Spans are analyzed.
How it works
The ARMS agent automatically selects a trace propagation protocol based on the headers present in each incoming request.
Selection flow
Consider a trace that passes through services A, B, and C. When each service receives a request, the ARMS agent follows this logic:
Scan request headers for protocol-specific fields. The scan follows a fixed priority order:
ARMS agent version Priority order (highest to lowest) v4.5.x and later W3C > EagleEye > SkyWalking > Jaeger > Zipkin v4.x to v4.4.x EagleEye > W3C > SkyWalking > Jaeger > Zipkin Earlier than v4.x EagleEye > Jaeger > Zipkin > SkyWalking > W3C If a matching header is found, the agent restores the trace context from the request and uses the same protocol to propagate context to downstream services.
If no matching header is found, the agent creates a new trace context and propagates it using the highest-priority protocol. By default, this is the EagleEye protocol.
Customize protocol priority
To change the default protocol priority, go to Configuration > Custom Configurations and update the Trace context propagation protocol settings section. For details, see Trace context propagation protocol settings.