Span Events and Logs
You'll learn: How to record timestamped events within spans to capture significant moments that help debug and understand request flow.
The Core Idea
While a span represents a unit of work with a start and end time, span events are timestamped snapshots of interesting moments within that span. Think of a span as a movie scene, and events as important frames you want to mark—a character entering, a door slamming, or a reveal moment.
Events capture occurrences like:
- Cache hit or miss
- Retry attempt initiated
- Database connection acquired
- Exception caught and handled
- Authorization check passed
Unlike span attributes (which describe the span as a whole), events represent specific instants in time with their own context.
Why Events Matter
When debugging a slow request, the overall span duration tells you that something was slow, but events tell you where the time went. Did the third retry succeed? Was data found in cache? Events provide a narrative timeline within the span's lifecycle.
Each event typically includes:
- Timestamp: when it occurred
- Name: what happened (e.g., "cache.hit")
- Attributes: contextual details specific to that event
Events vs Logs
While similar to logs, span events are attached to a specific span in your trace. This creates a direct link between "what happened" (the event) and "during which operation" (the span). Traditional logs might capture the same information but lack this structural relationship to the distributed trace.
Key Takeaway: Span events add timestamped milestones within a span, recording significant moments like cache hits or retries that help you understand not just what happened, but when and in what context during request processing.