Skip to main content
If both span events and span attributes can hold key-value pairs, how do you decide which to use? Here’s a simple rule of thumb:
  • If the timing of the action matters, use a span event.
  • If it’s descriptive context about the span, use an attribute.
Example scenario: file upload span
  • A user uploads a file and a virus scan runs during that flow.
    • Detecting a virus is a point-in-time action — it occurred at a specific moment during the span. Use a span event for that.
    • Details like file type and file size describe the span but are not tied to a single instant. Use span attributes for those.
Example (single, consolidated code snippet):
Note that even if a virus is not detected, you still usually want to record file details on the span; those belong as attributes because they describe the span regardless of whether the event occurred.
Use span events for time-specific occurrences and span attributes for persistent metadata describing the span.
Key distinctions and guidance
  • Timestamps
    • Span events include timestamps — they represent something that happened at a particular instant.
    • Span attributes do not carry separate timestamps; the span’s start/end times provide the temporal context.
  • Use cases for span events
    • Exceptions, errors, retries, milestones, logs — anything you want to mark at a specific moment.
    • Events can include their own attributes (for example, error.type, message).
  • Use cases for span attributes
    • Persistent metadata and context for the entire span — e.g., db.system, http.method, http.response.status_code, user.id, payment.method, file.type, file.size_kb.
  • Durations
    • If you need to represent an interval, rely on span start/end timestamps or a nested child span. Span events are single instants and cannot represent durations by themselves.
  • Exceptions
    • Exceptions are typically captured as events (many telemetry SDKs provide record_exception or an equivalent that generates an event).
Comparison table
ConceptUse WhenExample attributes / events
Span eventYou need a timestamped occurrence inside the spanspan.add_event("error", {"type":"TimeoutError"})
Span attributeYou need persistent contextual metadata for the spanspan.set_attribute("http.method", "GET")
Interval/durationYou need to express a time rangeUse span start/end or create a child span
Error reportingCapture the exact time of the errorrecord_exception() or span.add_event("exception", {...})
Summary
  • Use span events for time-specific actions, errors, or logs that matter at a precise instant.
  • Use span attributes for contextual, persistent details about a span that apply for its whole duration.
References and further reading This concludes the explanation of span events vs span attributes.

Watch Video