Span Context

A Trace ID is a globally unique, 16-byte or 128-bit identifier assigned to a single request's end-to-end journey. It is the primary correlation key, shared by every span within the same trace. This ID is generated by the root service (the trace's initial entry point) and must remain constant as the request propagates. It allows observability backends to group all related spans, reconstructing the complete request flow across services, queues, and databases.

A Span ID is a unique identifier for a single, specific unit of work within a trace. Unlike the Trace ID, it is local to its span. This ID is used to establish parent-child relationships between spans, forming the hierarchical structure of a trace. When a service calls another, the child span's ID is different from its parent's, but the parent's Span ID is recorded in the child's context as the parent span ID. This creates the directed acyclic graph (DAG) that visualizes call paths.

Trace Flags are a set of binary options carried in the span context that control tracing behavior. The most critical flag is the sampling bit. A value of 1 means the trace is sampled and should be recorded and exported to the backend. A value of 0 means it is not sampled. This decision, often made by the root service via head sampling, is propagated to all downstream services, ensuring they respect the sampling decision and avoid generating telemetry for unsampled requests, controlling cost and volume.

Trace State is a key-value map carried in the span context that provides additional, vendor-specific tracing information. It is designed for multi-vendor interoperability. For example, one tracing system can add an entry (vendorname=value) that another system can read and propagate without understanding its full semantics. It is used for features like:

• Passing sampling probabilities
• Carrying proprietary debug flags
• Encoding authentication tokens for trace ingestion Unlike other context fields, Trace State is mutable, allowing services to update their respective entries.

Span context is useless unless it can be transmitted. Propagation formats define the wire protocol for encoding context into carriers like HTTP headers or message metadata. The two primary standards are:

• W3C Trace Context: The modern, vendor-neutral W3C recommendation. Uses headers traceparent (carries Trace ID, Span ID, flags) and tracestate.
• B3 Propagation: The format pioneered by Zipkin. Uses headers prefixed X-B3-, such as X-B3-TraceId and X-B3-SpanId. Tracing libraries use propagators to inject (outbound) and extract (inbound) context using these formats.

It is crucial to distinguish between the immutable span context and the mutable span data. The context (Trace ID, Span ID, Flags, State) is the portable 'passport' that is propagated. The span's attributes (e.g., http.method=GET), events, status, and duration are recorded locally by each service and are not part of the propagated context. They are exported separately as span data and linked via the Span ID. This separation ensures the lightweight context propagation does not balloon with diagnostic details.

A propagator is a library component responsible for the mechanics of distributed context propagation. It injects trace context into outbound requests (e.g., HTTP headers, gRPC metadata, Kafka message properties) and extracts it from inbound requests.

• Format-Specific: Different propagators implement specific wire formats: W3C Trace Context, B3 Propagation (Zipkin), Jaeger, or proprietary formats.
• Process Boundary Bridge: This component is what makes span context "propagate," moving the immutable state across network calls, queues, or RPC boundaries to maintain trace continuity.

The Trace ID is a globally unique, random identifier (typically 16 or 32 bytes) assigned to a single request's end-to-end execution path. It is the primary correlation key for distributed tracing.

• Root Identifier: All spans generated as part of the same logical request share the same Trace ID.
• Immutable and Propagated: This ID is set at the very start of a request (e.g., by an ingress service or load balancer) and is a core component of the span context that gets propagated downstream.

A span is the fundamental unit of work in a trace, representing a named, timed operation corresponding to a contiguous segment of execution within a service.

• Represents Work: Examples include a database query, an HTTP handler, a function call, or a message processing loop.
• Contains Context: Each span contains its own span ID and a reference to its parent's span ID, forming a hierarchy. The span's context (trace ID, its own span ID, etc.) is used to create child spans.
• Building Block: A trace is a directed acyclic graph (DAG) composed of multiple, related spans.

Distributed context propagation is the overarching mechanism and practice of transmitting span context (and other baggage like correlation IDs) across process and network boundaries in a distributed system.

• Maintains Causality: It allows a downstream service to create spans that are correctly linked as children of the upstream span, preserving the causal chain.
• Implementation Channels: Context is typically propagated via HTTP headers, gRPC metadata, message queue properties (e.g., Kafka headers), or other framework-specific carriers.