Supported trace propagation protocols

ARMS supports five trace propagation protocols: EagleEye, W3C Trace Context, Zipkin, Jaeger, and SkyWalking. The ARMS agent automatically detects the protocol used by each incoming request and propagates the trace context accordingly.

EagleEye protocol

EagleEye is ARMS's native trace propagation protocol, developed by Alibaba Cloud and widely adopted across Alibaba Cloud services.

The protocol header includes the following fields:

• EagleEye-TraceID: a random 32-bit string that uniquely identifies the trace.

• EagleEye-RpcID: encodes the hierarchical relationship between spans. For example, in the sequence 0, 0.1, 0.2, 0.1.1, span 0 is the parent, and 0.1 and 0.2 are its children.

• EagleEye-SpanID: a random long integer, included for compatibility with open source redundant fields.

• EagleEye-pSpanID: a random long integer, included for compatibility with open source redundant fields.

• EagleEye-Sampled: indicates whether the trace is sampled.

• EagleEye-pAppName: the upstream applications.

• EagleEye-pRpc: the interface of the upstream application.

• EagleEye-UserData: baggage to propagate with the trace. Format: k1=v1&k2=v2.

W3C protocol

The W3C protocol is the default protocol used by the World Wide Web Consortium (W3C).

The protocol header includes the following fields:

• traceparent: encodes the trace ID, parent span ID, and sampling flag in a single header. Format: <2-bit version>-<32-bit trace ID>-<16-bit parent span ID>-<sampling flag>. Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01.

• tracestate: baggage to propagate with the trace. Example: k1=v1&k2=v2.

Zipkin protocol

The Zipkin protocol is used by open source Zipkin.

The protocol header includes the following fields:

• X-B3-TraceId: a 32-bit trace ID. Example: 0af7651916cd43dd8448eb211c80319c.

• X-B3-SpanId: a 16-bit span ID. Example: b7ad6b7169203331.

• X-B3-ParentSpanId: a 16-bit parent span ID. Example: b7ad6b7169203331.

• X-B3-Sampled: the sampling flag. 1 means the trace is sampled; 0 means it is not.

• baggage-: baggage to propagate with the trace. Example: baggage-k1=v1, baggage-k2=v2.

Jaeger protocol

The Jaeger protocol is used by open source Jaeger.

The protocol header includes the following fields:

• uber-trace-id: encodes the trace ID, span ID, parent span ID, and flag in a single header. Format: traceId:spanId:parentSpanId:flag. Example: 0af7651916cd43dd8448eb211c80319c:b7ad6b7169203331:b7ad6b7169203331:1.

• uberctx-: baggage to propagate with the trace. Example: uberctx-k1=v1, uberctx-k2=v2.

SkyWalking protocol

The SkyWalking protocol is used by open source SkyWalking.

• sw8: a hyphen-delimited header with eight fields. By default, the total header length must be under 2,000 characters. All string values must be Base64-encoded.

  Required fields:

  • Sample: 0 or 1. 0 means the context exists but can be ignored; 1 means the trace must be sampled and sent to the backend.

  • Trace ID: the unique identifier for the trace. A Base64-encoded string composed of three long values separated by periods (.).

  • Parent trace segment ID: the globally unique segment ID. A Base64-encoded string.

  • Parent span ID: 0 or a positive integer.

  • Parent service: a Base64-encoded string of more than 50 UTF-8 characters.

  • Parent service instance ID: a Base64-encoded string of more than 50 UTF-8 characters.

  • Parent service endpoint: the entry span endpoint of the parent trace segment. A Base64-encoded string of more than 50 UTF-8 characters.

  • Destination URL: the URL of the service the client is calling. The format may differ from <IP address><Port number>. A Base64-encoded string.

  Sample sw8 header: 1-TRACEID-SEGMENTID-3-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORT.

• sw8-x: an extension header with hyphen-delimited fields that can be added as needed.

  The tracking mode can be null, 0, or 1. null or 0 (default) means spans in the context are not analyzed. Context propagates upstream by default unless you explicitly change the tracking mode.

Select a trace propagation protocol

By default, the ARMS agent selects a trace propagation protocol by inspecting the headers of each incoming request.

Consider a trace path A > B > C, where A, B, and C are different applications. Each application follows this logic when it receives a request:

1. Search all request headers for a recognized protocol-specific header.

   • For ARMS agent v4.5.x and later, the search order is: W3C, EagleEye, SkyWalking, Jaeger, Zipkin.

   • For ARMS agent v4.x through v4.4.x, the search order is: EagleEye, W3C, SkyWalking, Jaeger, Zipkin.

   • For ARMS agent versions earlier than v4.x, the search order is: EagleEye, Jaeger, Zipkin, SkyWalking, W3C.

   If a matching header is found, proceed to step 2. Otherwise, proceed to step 3.

2. Restore the trace context from the request using the matched protocol, then use that same protocol to propagate the trace context to downstream applications.

3. If no valid protocol header is found, create a new trace context and propagate it using the highest-priority protocol. By default, EagleEye has the highest priority. To change the protocol priority, go to the Trace context propagation protocol settings section on the Configuration > Custom Configurations tab. For more information, see Context propagation settings.