SpanIDs

SpanID is an identifier used to represent a single span within a distributed trace. In tracing systems, a trace is composed of multiple spans that together describe a distributed operation, and the SpanID uniquely identifies each individual span within its trace. The combination of a TraceID and a SpanID enables tracing systems to reconstruct the full execution path and relationships between spans.

Format and scope

SpanID is typically an 8-byte value, commonly encoded as 16 hexadecimal characters. It is unique within a single trace, meaning no two spans in the same trace should share the same SpanID. However, SpanIDs are not guaranteed to be globally unique across different traces; uniqueness is scoped to the trace context in which they are used. SpanIDs are transmitted as part of the span context, alongside the TraceID and, in many protocols, trace flags or other metadata.

Generation and semantics

SpanIDs are usually generated by instrumentation libraries or tracing agents when a new span is created. The goal is to minimize the chance of collisions within a trace, often using random or pseudo-random number generation. The SpanID itself is opaque to most applications, serving mainly as a stable identifier to correlate events, logs, and measurements that belong to the same span.

Parent-child relationships

Each non-root span has a parent span, identified by the parent’s SpanID. In common propagation formats, the parent’s SpanID is carried in the span context or trace headers. The root span typically has a zero-valued parent-id. The SpanID of the current span is distinct from its parent’s, enabling the construction of a hierarchical trace graph.

Propagation and usage

When a request propagates across services, the trace context—including the TraceID and the relevant SpanIDs—flows to downstream components. Downstream services create new child spans with new SpanIDs while preserving the shared TraceID, thereby maintaining the trace continuity across systems. SpanIDs are fundamental for correlating logs, metrics, and traces.