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

Span Events and Logs

Recording timestamped events within a span to capture significant moments like retries, cache hits, or exceptions.

Span Events and Logs

What you'll learn: How to record timestamped events within a span to capture significant moments during request processing.

The Core Idea

While a span represents a unit of work with a start and end time, span events (also called span logs) let you record specific moments within that work. Think of a span as a movie scene—the span itself has a duration, but events are like subtitles marking key dialogue or actions as they happen.

Events are timestamped annotations that capture significant occurrences like retries, cache hits, exceptions, or state transitions. Unlike span attributes (which describe the entire operation), events mark discrete points in time.

Why Events Matter

When debugging a slow request, knowing it took 500ms isn't enough. You need to know where in that 500ms things went wrong. Did the database connection retry three times? Did the cache miss? When exactly did the timeout exception occur?

Events answer these questions by providing a timeline within your span.

Common Event Use Cases

  • Retries: Log each retry attempt with a timestamp
  • Cache operations: Record cache hits, misses, or invalidations
  • Exceptions: Capture when errors occur without ending the span
  • State changes: Mark transitions in a workflow (e.g., "payment_authorized", "order_validated")
  • External calls: Note when you initiated a third-party API call

Each event typically includes a timestamp, a name, and optional key-value attributes providing context about what happened at that moment.

Key Takeaway: Span events are timestamped markers within a span that record significant moments like retries, cache operations, or exceptions, giving you a detailed timeline of what happened during request processing.