Propagator

The propagator injects the current trace context into the headers of an outbound request. This context includes the Trace ID, Span ID, and other metadata like trace flags and trace state. The specific headers and their format are dictated by the chosen propagation standard (e.g., traceparent for W3C, X-B3-TraceId for B3). This injection is what allows the next service in the chain to link its work to the ongoing trace.

On the receiving end of a request, the propagator extracts the trace context from the incoming request's headers. It parses the headers according to the expected wire format and reconstructs a SpanContext object. This extracted context is then used to create a child span, ensuring the new operation is correctly parented within the existing trace. If no context is found, the propagator may start a new root trace.

A propagator implements a specific wire format protocol for serializing and deserializing trace context. Common standards include:

• W3C Trace Context: The modern, vendor-neutral standard using traceparent and tracestate HTTP headers.
• B3 Propagation: The format used by Zipkin, with headers like X-B3-TraceId and X-B3-SpanId.
• Jaeger Propagation: Extends B3 with additional headers like uber-trace-id. The propagator must handle edge cases like multi-header formats and malformed data gracefully.

In heterogeneous environments, services may use different propagation formats. A robust propagator often supports multiple formats simultaneously. It will attempt extraction using a prioritized list of formats (e.g., try W3C first, then B3). Some advanced implementations can even inject context in multiple formats in a single outbound request to ensure compatibility with all downstream services, a pattern known as dual propagation.

Beyond basic trace identifiers, many propagators are also responsible for handling distributed baggage. Baggage consists of key-value pairs that are propagated alongside the trace context, allowing user-defined data (e.g., user-id, feature-flag) to be passed transparently through the call chain. The propagator must inject and extract these baggage items according to the protocol's rules, often using a separate header like baggage.

The propagator does not work in isolation. It is integrated into the tracing SDK's instrumentation for network clients and servers. For example:

• In an HTTP client interceptor, it calls the inject method before sending the request.
• In an HTTP server middleware, it calls the extract method as the first operation. This integration is often abstracted by frameworks (like OpenTelemetry's TextMapPropagator interface), allowing developers to swap propagation schemes without changing application code.

The OpenTelemetry SDK provides a pluggable architecture for propagators, implementing the TextMapPropagator interface. Key built-in implementations include:

• W3C TraceContext Propagator: Handles the traceparent and tracestate headers as per the W3C recommendation.
• W3C Baggage Propagator: Manages the propagation of correlation context (baggage header).
• B3 Propagator: Supports the Zipkin-originated B3 Propagation format (single and multi-header variants).
• Jaeger Propagator: Handles the uber-trace-id header format used by Jaeger. Developers configure the global propagator via GlobalPropagators.set() to define the wire format for their services.

This is the core abstraction for propagators in OpenTelemetry. It defines two critical methods:

• inject(context, carrier, setter): Injects the current span context (trace ID, span ID, etc.) from the given context.Context into a carrier object (e.g., HTTP request headers). The setter is a callback that knows how to insert a key-value pair into that specific carrier type.
• extract(context, carrier, getter): Extracts a span context from an incoming carrier (e.g., HTTP response headers) using the provided getter callback. It returns a new context.Context containing the extracted span context, or an invalid one if no context was found. This interface enables propagators to work with any transport (HTTP, gRPC, Kafka, etc.) via carrier-specific getter/setter functions.

Propagators extend beyond HTTP to asynchronous communication. For systems like Apache Kafka, RabbitMQ, or AWS SQS, the trace context is injected into and extracted from message metadata (headers).

• Carrier: The message's header map.
• Challenge: Context must survive queueing and processing delays, linking producer and consumer spans across different traces via span links.
• Implementation: SDKs provide helper getter and setter functions for common messaging clients. For example, the OpenTelemetry Kafka instrumentation uses a propagator to inject context into ProducerRecord.headers.

Real-world deployments often require multiple propagation formats.

• Composite Propagator: Chains several propagators together. The SDK will attempt extraction using each propagator in sequence until one succeeds. This is essential for migrating between formats (e.g., from B3 to W3C) or in heterogeneous environments.
• Custom Propagator: Organizations can implement the TextMapPropagator interface for proprietary header formats or to add business-specific context to the propagation carrier. This is also used for trace enrichment at the edge by injecting additional metadata (e.g., tenant ID) that downstream services can extract.

Auto-instrumentation agents (e.g., Java Agent, .NET CLR Profiler) handle propagator configuration automatically. They detect common web and RPC frameworks and inject the appropriate instrumentation, using a default propagator (often W3C).

• Environment Variables: The propagator can be configured via OTEL_PROPAGATORS, accepting values like tracecontext,baggage,b3.
• Priority: The agent's configured propagator overrides any programmatic setup in the application code, ensuring consistency across a fleet of services instrumented via agents.

gRPC uses HTTP/2 as its transport, so propagation occurs via HTTP headers. However, the integration is framework-specific.

• OpenTelemetry gRPC Instrumentation: Provides interceptors (ClientInterceptor, ServerInterceptor) that automatically call the configured propagator's inject and extract methods on the gRPC metadata object.
• Carrier: The Metadata object (key-value pairs).
• Process: On the client side, the interceptor injects context into outgoing metadata. On the server side, the interceptor extracts context from incoming metadata, creating a proper parent-child relationship between the client and server spans.

The immutable state that a propagator is responsible for transmitting. It contains the core identifiers and flags necessary for trace continuity, including:

• Trace ID: The globally unique identifier for the entire request.
• Span ID: The identifier for the current unit of work.
• Trace Flags: Bits that control behavior, most notably the sampling decision.
• Trace State: A key-value map for carrying vendor-specific trace data. The propagator's sole function is to inject this context into outbound calls and extract it from inbound calls.

The modern, standardized wire format for trace propagation, defined as a W3C Recommendation. It uses two primary HTTP headers:

• traceparent: Carries the version, trace ID, span ID, and trace flags in a compact, delimited string.
• tracestate: Carries supplemental vendor-specific data in a key-value format. A W3C propagator is the most common implementation today, ensuring interoperability between different programming languages, frameworks, and observability backends (e.g., Jaeger, Zipkin, commercial APMs).

An earlier, de-facto standard propagation format pioneered by the Zipkin tracing system. It uses multiple HTTP headers prefixed with X-B3-, such as:

• X-B3-TraceId
• X-B3-SpanId
• X-B3-ParentSpanId
• X-B3-Sampled While largely superseded by W3C Trace Context for HTTP, B3 remains prevalent in legacy systems and some non-HTTP protocols (e.g., gRPC metadata, Kafka headers). A robust tracing library often includes both B3 and W3C propagators.

The vendor-neutral framework where propagators are concretely implemented. In OpenTelemetry, the Propagator interface is defined in the API SDK. Key implementations include:

• W3CTraceContextPropagator: For W3C Trace Context.
• B3Propagator: For single-header (b3) and multi-header (X-B3) B3 formats.
• CompositePropagator: Allows multiple propagators (e.g., W3C and baggage) to work together. The OTel SDK uses these propagators automatically within its HTTP client/server instrumentation, handling context propagation transparently for developers.

The code that generates tracing data (spans). Propagators are a critical sub-component of instrumentation. The relationship is hierarchical:

1. Instrumentation wraps a library (e.g., requests in Python, fetch in Node.js).
2. It uses the Tracer to create spans.
3. The Tracer uses the registered Context.
4. The Context is managed by the Propagator at system boundaries. In auto-instrumentation, this entire chain—including propagator setup—is configured automatically by an agent, requiring zero code changes.

The broader architectural pattern that trace propagation is a part of. It encompasses:

• Mechanism: The propagator component itself.
• Carrier: The medium that transports the context (e.g., HTTP headers, gRPC metadata, AMQP properties, Kafka message headers).
• Format: The serialization standard (W3C, B3).
• Scope: Extending beyond just traces to include baggage (user-defined key-value pairs) and other correlation context (e.g., log correlation IDs). This pattern is essential for maintaining a consistent request context across asynchronous and synchronous calls in a microservices architecture.