Understand Span Events

Span events are structured, timestamped records attached to a span. They capture discrete occurrences during a span's lifetime — such as exceptions, state transitions, or application-specific milestones — without creating a separate span.

What are span events?

In OpenTelemetry, a span event is a log-like record attached to a specific span. Each event has:

• A name identifying what happened (e.g., exceptionCopy, cache.missCopy, retryCopy)
• A timestamp recording when it occurred
• Zero or more attributes with additional context

Unlike child spans, events do not have their own duration or parent-child hierarchy. They are lightweight annotations that enrich a span with point-in-time context.

Common use cases

• Exception recording — Most OpenTelemetry SDKs automatically record exceptions as span events with the name exceptionCopy and attributes exception.typeCopy, exception.messageCopy, and exception.stacktraceCopy.
• Retry attempts — Recording each retry as an event on the enclosing span rather than creating a separate span per attempt.
• State transitions — Marking when a connection was established, a lock was acquired, or a fallback was triggered.

Why do span events exist when we have log records?

Span events are a historical artifact of how OpenTelemetry evolved. OpenTelemetry was formed in 2019 by merging OpenTracing and OpenCensus, two projects focused on traces (and OpenCensus on metrics). Logs were explicitly out of scope in the early design — the project acknowledged that a mature ecosystem of logging libraries already existed and chose not to compete with it.

However, traces still needed a way to record point-in-time occurrences within a span, such as exceptions or retries. Without a Logs signal to lean on, the Tracing API included Span.AddEventCopy and Span.RecordExceptionCopy as built-in methods. These span events became the standard way for OpenTelemetry instrumentations to record discrete happenings during a span's lifetime.

When OpenTelemetry later added the Logs signal and defined log-based events — log records with an event_nameCopy field, automatically correlated with the active span via trace context — it became clear that there were now two overlapping mechanisms for the same purpose. The community has since converged on a simpler model: events are log records emitted via the Logs API, correlated with spans through trace context, and the span event APIs are being deprecated.

Span events in Dash0

Viewing span events

Span events appear in two places in the Dash0 UI:

• Events & Logs tab — When inspecting a span in the sidebar, the Events & Logs tab shows all log records and span events associated with that span.
• Trace View — In the Waterfall and Flame Graph visualizations, span events are rendered as markers on the span's timeline bar.

Span event column in the Span Table

The Span Table includes an optional Events column that shows the count of span events for each span. This column can be toggled from the display menu.

Querying span events

Span events contribute to the dash0.span.eventsCopy synthetic metric, which counts span events over time and supports filtering and grouping by span event, span, and resource attributes.

Example PromQL query to count exception events by service:

1
sum by (service_name) (rate({otel_metric_name = "dash0.span.events", otel_span_event_name = "exception"}[$__interval]))

Deprecation and migration to log records

OpenTelemetry is deprecating span events in favor of log records linked to spans via trace context. Under this model, events become log records related with the original span through trace context, removing the per-span limits and enabling improved querying and alerting.

Dash0 supports this migration with a per-dataset option to automatically convert span events to log records during ingestion. When enabled, each span event is transformed into a correlated log record and the original span events are removed from the span.