Duration vs. Moment in Time
It is easy to confuse spans and events because both are part of the tracing data model. The distinction is fundamental: spans have duration, events do not.
- A Span represents an interval of time. It has a start and an end. "This database query started at T+100ms and finished at T+340ms."
- An Event is a point in time. It is a timestamped annotation that occurs within a span at a specific instant. "At T+215ms, the connection pool was exhausted."
Think of a span as a container for a piece of work. Inside that container, you can log specific moments of interest as events — like sticky notes attached to a timeline.
Practical Use of Events
Events are most commonly used for two purposes:
1. Logging exceptions and errors. When an exception is thrown inside a span, you attach it as an event with the full stack trace. This is far more powerful than a log line because the exception is automatically correlated with the trace, the service, and the exact moment in the request lifecycle where it occurred.
2. Marking significant state transitions. For example, a span called process-payment might contain events like "payment_gateway_contacted", "fraud_check_passed", and "charge_submitted". These events don't have duration themselves, but they give you a narrative of what happened inside the span.
In OTel SDK terms, this means starting a span for the unit of work (like processing a payment), and when an exception is caught inside it, recording that exception directly onto the span — which attaches the stack trace as an event and marks the span's status as an error — rather than just logging it separately.
The key insight for senior engineers: events inside spans give you structured, correlated debugging context that plain log lines cannot. A log line says "error occurred." A span event says "this error occurred at this exact point in this specific request's journey, which also involved these 12 other services."