B3 Propagation

The X-B3-TraceId header carries a 128-bit or 64-bit globally unique identifier for the entire request trace. This ID is generated by the root service and must be propagated unchanged to all downstream services, enabling the correlation of all spans belonging to a single user request. It is typically represented as a 32-character (128-bit) or 16-character (64-bit) hexadecimal string.

• Purpose: Uniquely identifies the end-to-end request.
• Format: 32 or 16 character lowercase hex string (e.g., 463ac35c9f6413ad48485a3953bb6124).
• Generation: Created once by the initiating service.

The X-B3-SpanId header carries a 64-bit identifier for the current unit of work (span) within a service. Each service creates a new Span ID for its operation. This ID, combined with the Trace ID, uniquely identifies a specific span in the distributed system.

• Purpose: Identifies a single operation within a service.
• Format: 16 character lowercase hex string (e.g., a2fb4a1d1a96d312).
• Parent-Child: The Span ID of a parent span is passed to a child service as the X-B3-ParentSpanId.

The X-B3-ParentSpanId header is optional and is used to explicitly define the parent-child relationship between spans. When a service (the client) calls another service (the server), it includes its own Span ID in this header. The receiving service uses this to link its new span as a child of the caller's span, constructing the trace's call graph.

• Purpose: Establishes direct parentage between spans.
• Inclusion: Sent by a calling service to the service it invokes.
• Absence: If omitted, the receiving span is considered a root span within that trace.

The X-B3-Sampled header communicates the sampling decision for the trace. It is a single-character flag ('1', '0', 'd') that instructs downstream services whether to record and export span data for this request, which is critical for managing telemetry volume and cost.

• '1': Debug. Record and export this trace, overriding any other sampling configuration.
• '1': Sample. Record and export this trace.
• '0': Do not sample. Process the request but do not record/export spans.
• Decision Point: Typically made by the root service or a gateway.

The X-B3-Flags header is used to communicate specific control flags for the trace. The most significant flag is the debug flag, which takes precedence over the X-B3-Sampled header. This header uses a bitmask representation, though it is often seen as a decimal integer ('1' for debug).

• Debug Flag (bit 0): When set to 1, it forces sampling for the entire trace, regardless of other rules. This is used for actively troubleshooting specific requests.
• Legacy Use: In older implementations, X-B3-Flags: 1 was equivalent to X-B3-Sampled: 1.
• Precedence: Debug flag overrides all other sampling configurations.

B3 headers are injected into outbound HTTP requests by a propagator in the tracing SDK and extracted from inbound requests. While a de facto standard, B3 is largely superseded by the vendor-neutral W3C Trace Context standard for better interoperability. Modern systems often support both.

• Injection/Extraction: Handled automatically by tracing libraries (e.g., OpenTelemetry SDK).
• Limitation: B3 only supports a single parent, while W3C TraceContext supports multiple linked contexts.
• Coexistence: Systems can be configured to read both B3 and W3C headers, with a defined precedence order for backward compatibility.

In brownfield deployments and legacy microservice architectures built before the W3C Trace Context standard, B3 is often the de facto propagation format. Many older service meshes (like early Linkerd versions) and frameworks (like Spring Cloud Sleuth) defaulted to B3. Migrating these systems can be costly, so B3 remains in active use to maintain backward compatibility and avoid trace breakage.

Several service mesh implementations support B3 Propagation for trace context passing, often alongside other formats. For example:

• Istio can be configured to propagate B3 headers.
• Envoy proxy includes built-in support for generating and propagating B3 headers. This allows traces to flow seamlessly through the data plane, even if application code is not fully instrumented, providing network-level observability.

Modern observability pipelines and backends are designed to handle multiple propagation formats simultaneously. Tools like the OpenTelemetry Collector can receive, parse, and normalize traces using B3, W3C Trace Context, and other formats into a single standard (like OTLP). This allows organizations with heterogeneous systems to maintain a unified view without forcing a immediate, system-wide format change.

Many language-specific tracing SDKs and auto-instrumentation agents offer B3 support to ensure interoperability. For instance:

• The OpenTelemetry SDKs for Java, Go, Python, etc., include B3 propagators.
• Jaeger client libraries often support B3 alongside their native Uber headers. This ensures that services written in different programming languages can participate in the same trace when B3 is the chosen wire protocol.

B3 headers can be embedded within the metadata of asynchronous messaging systems (like Kafka, RabbitMQ) and RPC frameworks (like gRPC) to propagate trace context across non-HTTP boundaries. While less standardized than HTTP, this practice is used to trace workflows that involve message queues, ensuring the causal chain is not broken by asynchronous processing.

This is the general mechanism for passing trace context (like Trace ID, Span ID) across service boundaries. It ensures a request's journey can be reconstructed.

• Carriers: Context is embedded in transport protocols, commonly as HTTP headers (for B3, W3C) or in message metadata (e.g., Kafka, gRPC).
• Process: A propagator component in the tracing SDK handles injecting context into outbound requests and extracting it from inbound requests.

Span context is the immutable state that must be propagated. It is the payload carried by formats like B3. Its core components are:

• Trace ID: The global identifier for the entire request.
• Span ID: The identifier for the current unit of work.
• Trace Flags: Contains the sampling decision (e.g., sampled=1).
• Trace State: Provides additional vendor-specific trace data (more flexible than B3's limited headers). This context is created at the start of a span and passed along to create child spans.

A propagator is the concrete implementation in a tracing library (e.g., OpenTelemetry SDK) that serializes and deserializes span context according to a specific wire format.

• B3 Propagator: Injects/extracts the X-B3-* headers.
• W3C TraceContext Propagator: Handles the traceparent header.
• Composite Propagator: Used to support multiple formats simultaneously (e.g., both B3 and W3C) for backward compatibility in heterogeneous environments.

Propagation headers like B3's X-B3-Sampled communicate the sampling decision—whether this trace should be recorded and exported. This controls data volume and cost.

• Head Sampling: The decision is made at the trace's start (root span). The sampling flag (1 or 0) is propagated to all downstream services, ensuring the entire trace is either recorded or dropped consistently.
• Tail Sampling: The decision is made after trace completion based on its full data (e.g., only keep traces with errors). This requires all spans to be sent to a central processor (like the OpenTelemetry Collector) before the decision is made.