Course contentsShow
← System Design
Lesson 1226 of 1,91931. Observability: TracingFree lesson

Span Events and Logs

Recording timestamped events within a span to capture significant moments like cache hits or retry attempts.

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.