> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Span Events vs Span Attributes
> Explains when to use span events for timestamped occurrences and span attributes for persistent contextual metadata in traces
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):
```python theme={null}
# Add a point-in-time event when the virus is detected
span.add_event("virus_detected")
# Attach descriptive metadata about the file to the span
span.set_attribute("file.type", "pdf")
span.set_attribute("file.size_kb", 328)
```
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
| Concept | Use When | Example attributes / events |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| Span event | You need a timestamped occurrence inside the span | `span.add_event("error", {"type":"TimeoutError"})` |
| Span attribute | You need persistent contextual metadata for the span | `span.set_attribute("http.method", "GET")` |
| Interval/duration | You need to express a time range | Use span start/end or create a child span |
| Error reporting | Capture the exact time of the error | `record_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
* [OpenTelemetry Tracing Concepts](https://opentelemetry.io/docs/concepts/signals/traces/)
* [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/)
This concludes the explanation of span events vs span attributes.