Span Lifecycle and Structure
What you'll learn: How a span is created, what data it must contain, and how its lifecycle flows from start to finish.
The Journey of a Span
A span represents a single unit of work in a distributed trace. Think of it like a stopwatch that records one operation—you press start when work begins, press stop when it ends, and the stopwatch captures the duration along with notes about what happened.
Required Span Fields
Every span must contain these essential pieces of information:
Operation Name
A human-readable identifier describing what work this span represents (e.g., db.query, http.request, process_payment). This helps you quickly understand what each span does when viewing traces.
Start Time
A timestamp marking when the operation began. This is typically captured as nanoseconds since epoch to provide precise timing.
End Time
A timestamp marking when the operation completed. The difference between end time and start time gives you the span duration—one of the most valuable metrics for understanding performance.
Span Context
As you've learned, this includes the trace ID, span ID, and parent span ID that link spans together into a complete trace.
The Lifecycle Flow
- Creation: A span is created when an operation starts, recording the start time and operation name
- Active: While active, the span can collect attributes, events, and status updates
- Completion: When the operation finishes, the end time is recorded
- Export: The completed span is sent to your tracing backend for storage and analysis
This lifecycle ensures you capture accurate timing data without interfering with your application's performance.
Key Takeaway: A span's structure revolves around three critical timestamps (start, end, duration) and a descriptive operation name, following a create-record-complete-export lifecycle that enables precise performance analysis across distributed systems.