What Is a Span? The Unit of a Trace Explained
A span is a single named, timed operation inside a trace, the basic building block that, combined with other spans, forms the full picture of a request.
If a trace is the story of a request, a span is one sentence in it. Spans are where the actual timing and detail of distributed tracing live. Understanding spans is the key to reading any trace, because everything a trace tells you is the sum of its spans.
What a span captures
A span records the name of an operation, its start and end times (and therefore its duration), and its status: success or error. It also carries identifiers, its own span ID, the parent span ID, and the shared trace ID, that let it be placed correctly within the trace tree.
Attributes and events
Spans hold attributes, key-value pairs that describe the operation, such as the HTTP method, the database statement, or a job name. They can also record events: timestamped points within the span, like a retry or a cache miss. These details are what turn a bare timing into something diagnostic.
Nesting and the span tree
Spans form a parent-child hierarchy. A request span might have child spans for each downstream call, and those children their own children. The nesting encodes causality and timing: you can see which operations happened inside which, and which ran in parallel versus in sequence.
Root and child spans
The root span is the one with no parent, representing the whole operation, the inbound request or the entire pipeline run. Every other span descends from it. The root span duration is the total time for the operation, and the child spans explain how that time was distributed.
Spans in CI/CD
When you trace a pipeline, each job or step becomes a span: the run is the root span, jobs are its children, and steps are theirs. Span durations and statuses then show precisely which step is slow or failing, the build equivalent of finding the bottleneck call in a request trace.
Key takeaways
- A span is one named, timed operation within a trace.
- Spans carry attributes, events, and parent/trace IDs.
- They nest into a tree that encodes causality and timing.
- In a traced pipeline, jobs and steps map to spans.