This topic describes the trace propagation protocols supported by Application Real-Time Monitoring Service (ARMS).
EagleEye protocol
The EagleEye protocol is developed by ARMS and is widely used in Alibaba Cloud.
The protocol header contains the following information:
EagleEye-TraceID: a random 32-bit string.
EagleEye-RpcID: the hierarchical relationship between the spans. Example: 0, 0.1, 0.2, 0.1.1. In this example, 0 is the parent span, and 0.1 and 0.2 are the child spans.
EagleEye-SpanID: a random long integer compatible with open source redundant fields.
EagleEye-pSpanID: a random long integer compatible with open source redundant fields.
EagleEye-Sampled: specifies whether the traces are sampled.
EagleEye-pAppName: the upstream applications.
EagleEye-pRpc: the upstream application interface.
EagleEye-UserData: the baggage to be propagated in the traces. 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 contains the following information:
traceparent: Format:
<2-bit version number>-<32-bit trace ID>-<16-bit parent span ID>-<Sampling identifier>. Example:00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01.tracestate: the baggage to be propagated in the traces. Example:
k1=v1&k2=v2.
Zipkin protocol
The Zipkin protocol is used by open source Zipkin.
The protocol header contains the following information:
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 identifier. For example, 1 indicates that the traces are sampled whereas 0 indicates that the traces are not.
baggage-: the baggage to be propagated in the traces. Example:
baggage-k1=v1, baggage-k2=v2.
Jaeger protocol
The Jaeger protocol is used by open source Jaeger.
The protocol header contains the following information:
uber-trace-id: Format:
traceId:spanId:parentSpanId:flag. Example:0af7651916cd43dd8448eb211c80319c:b7ad6b7169203331:b7ad6b7169203331:1.uberctx-: the baggage to be propagated in the traces. Example:
uberctx-k1=v1, uberctx-k2=v2.
SkyWalking protocol
The SkyWalking Protocol is used by open source SkyWalking.
sw8: consists of eight fields. Separate fields with hyphens (-). The default maximum number of characters in the protocol header must be less than 2,000. The protocol header contains the following fields. All string values must be Base64-encoded.
The following fields are required:
Sample: 0 or 1. 0 indicates that the context exists and can be ignored. 1 indicates that the traces need to be sampled and sent to the backend.
Trace Id: the unique identifier of the tracing operation. The value is a Base64-encoded string. The string consists of three long values that are separated with periods (.).
Parent trace segment Id: the globally unique segment ID. The value is a Base64-encoded string.
Parent span ID: 0 or a positive integer.
Parent service: a Base64-encoded string. The string must consist of more than 50 UTF-8 characters.
Parent service instance ID: a Base64-encoded string. The string must consist of more than 50 UTF-8 characters.
Parent service endpoint: the endpoint of the first entry span in the parent trace segment. The value is a Base64-encoded string. The string must consist of more than 50 UTF-8 characters.
Destination URL of the request: the URL of the destination service that the client wants to access. The format of the URL can be different from
<IP address><Port number>. The value is a Base64-encoded string.
Sample sw8 protocol header:
1-TRACEID-SEGMENTID-3-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORT.sw8-x: Separate fields with hyphens (-). Fields can be extended.
The tracking mode can be set to null, 0, or 1. The default value null or 0 indicates that all the spans generated in the context are not analyzed. Context is propagated upstream by default, unless changed during tracking.
Select a trace propagation protocol
By default, the ARMS agent selects the corresponding trace propagation protocol based on whether a specified protocol header is included in the header of a request.
Take the A > B > C traces as an example, where A, B, and C are different applications. When they receive a request, they sequentially follow the logic below to select a trace propagation protocol:
Search all headers of the request for any protocol-specific headers.
For the ARMS agent v4.x and later, the search order is: EagleEye, W3C, SkyWalking, Jaeger, Zipkin.
For the ARMS agent earlier than v4.x, the search order is: EagleEye, Jaeger, Zipkin, SkyWalking, W3C.
If a header corresponding to a specific trace propagation protocol is found, proceed to Step 2; otherwise, proceed to Step 3.
When a header corresponding to a specific protocol is present, first restore the trace context from the request based on that protocol, and then use this protocol to propagate the trace context for subsequent calls to downstream applications.
If no valid protocol headers are found in the request, create a new trace context, and then follow the highest-priority protocol to propagate the trace context later. The default highest-priority protocol is the EagleEye protocol. You can modify the protocol priority in the Trace context propagation protocol settings section of the Configuration > Custom Configurations tab. For more information, see Trace context propagation protocol settings.