diff --git a/content/en/blog/2026/deprecating-span-events.md b/content/en/blog/2026/deprecating-span-events.md new file mode 100644 index 000000000000..c10d77d4cf1f --- /dev/null +++ b/content/en/blog/2026/deprecating-span-events.md @@ -0,0 +1,188 @@ +--- +title: Deprecating Span Events API +linkTitle: Deprecating Span Events API +date: 2026-03-17 +author: >- + [Liudmila Molkova](https://github.com/lmolkova) (Grafana Labs), [Robert + Pająk](https://github.com/pellared) (Splunk), [Trask + Stalnaker](https://github.com/trask) (Microsoft) +sig: Specification, Logs +cSpell:ignore: Liudmila Molkova Pająk +--- + +OpenTelemetry is deprecating the Span Event API. This post explains why we’re +making this change, what it means at a high level, and how you can prepare. In +short: + +- We want to remove confusion and duplication caused by having two overlapping + ways to emit events: span events and log-based events. +- New code should write events as logs that are correlated with the current + span. +- The older "span events" style will be phased out over time, but existing data + and views that show events on spans will keep working. + +## Why deprecate the Span Event API? + +Today, OpenTelemetry offers two main ways to emit events that are correlated +with traces: + +- Span events, created via the + [Tracing API](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/trace/api.md) + using methods `Span.AddEvent` or `Span.RecordException`. +- Log-based events, emitted via the + [Logs API](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md) + (either directly or through logging libraries bridged into OpenTelemetry) and + associated with the active context. + +Having two competing APIs for the same concept has several drawbacks: + +- **Split guidance for instrumentation authors.** Library and framework authors + must choose between two ways of emitting very similar data. Different choices + lead to inconsistent user experiences across the ecosystem. +- **Duplicate concepts for users.** Operators must understand both span events + and log events, how they are exported, and how their backends treat them. +- **Slower evolution.** Improvements to the event model (for example, around + schemas, attributes, and backward-compatibility) must be specified and + implemented in two places. + +The OpenTelemetry community has been converging on a simpler mental model: +**events are logs with names** emitted via the Logs API, correlated with traces +and metrics through context, rather than as a special case on spans. This change +is significant because it unifies how OpenTelemetry represents events. + +At the same time, we recognize that span events are widely used today. Many +backends present span events in dedicated trace views, and some users depend on +events being sent in the same OTLP export payload as their parent span. + +The plan in [OTEP 4430: Span Event API deprecation plan][OTEP] aims to balance +these goals: + +- Provide **clear, consistent guidance** that new events should go through the + Logs API. +- **Preserve existing workflows** that depend on span events in traces, via a + compatibility layer. + +In short, we are deprecating the **API** for recording span events, not the +ability to see events attached to spans. + +## What is changing? + +The deprecation focuses on **how new events are recorded**: + +- OTLP support for log-based events is already stable, and the Logs API can + capture everything span events historically carried, with richer metadata and + more flexible export and filtering. +- The tracing specification will deprecate APIs such as `Span.AddEvent` and + `Span.RecordException` in favor of emitting log-based events. +- Language APIs and SDKs will make log-based events first-class, and provide + compatibility options that can still surface those events as span events where + needed. +- Instrumentations and semantic conventions will gradually move from span events + to log-based events in their next major versions, while keeping existing + behavior stable until then. + +## What stays the same? + +Even though the Span Event API is being deprecated, several important aspects of +user experience are intentionally preserved: + +- **Correlation across signals continues to work the same way.** Log-based + events still participate in OpenTelemetry context. +- **Existing data remains valid.** Data that already uses span events remains + part of the supported OTLP trace model. + +Deprecation is about providing a single recommended way to emit events in new +code, not about removing visibility into events on spans. + +## What should you do? + +First and foremost, we want this transition to be safe, gradual, and compatible +with the workflows you rely on today. + +Depending on your role, here is how the upcoming changes can affect you and what +you can do. + +### Operators + +If you mainly consume traces, logs, and metrics in dashboards and analysis +tools: + +- You should not need to change your applications or dashboards immediately. +- When you upgrade, your instrumentations may emit exceptions and other events + as log-based events rather than span events. Verify that events still appear + in the views you rely on (for example, span timelines and event views). + +### Application developers + +If you maintain an application that you instrument: + +- You should not need to change code immediately. +- Watch for new versions of your instrumentation libraries as they may start + emitting log-based events. However, they may still have an option to keep + using span events. +- The SDK will offer you a way transform log-based events back onto span events. + +If you maintain your own custom instrumentation: + +- Prefer the Logs API for new events and exceptions. +- Avoid adding new dependencies on span event methods, especially where they are + already marked as deprecated. + +### Observability vendors + +If you build observability backends or services: + +- Support ingestion of log-based events. +- Ensure that log-based events can still be surfaced in existing span-oriented + views where users expect them. + +### Instrumentation authors + +If you author OpenTelemetry instrumentations: + +- Keep existing stable major versions behaviorally compatible for now. +- Consider adding an opt-in mechanism in current major versions (like + [`OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN`](/docs/specs/semconv/exceptions)) to + emit log-based events alongside existing span events. +- For the next major versions, plan to migrate events and exceptions to the Logs + API following updated semantic conventions, rather than adding new span + events. + +### Semantic convention authors + +If you define or maintain OpenTelemetry semantic conventions: + +- Document events as log-based events, specifying attributes and event names for + log records instead of span events. +- When evolving existing conventions that currently rely on span events, provide + clear guidance on their log-based equivalents. + +### OpenTelemetry maintainers + +If you maintain OpenTelemetry language APIs and SDKs: + +- Expose and stabilize the Logs API so that end users can easily emit log-based + events. +- Prepare for the deprecation of span event methods such as `Span.AddEvent` and + `Span.RecordException` in favor of log-based events, while maintaining + compatibility where needed. +- Provide helpers or configuration that can transform log-based events back onto + span events for users and backends that still depend on that representation. + +## Closing + +Please share your requirements and concerns in +[community#3312](https://github.com/open-telemetry/community/issues/3312). We +are especially interested in which compatibility aspects matter most to you, for +example, whether you rely on seeing events directly on spans in trace views, on +having events included in the same OTLP export payload as their parent spans, or +on other behaviors your current tooling depends on. + +Deprecation here does **not** mean removing span events. It is about shifting +the recommended way to emit new events toward the Logs API. + +Our goal is to make events in OpenTelemetry **simpler, more consistent, and more +powerful**, while providing a graceful transition to the new recommendations. + +[OTEP]: + https://github.com/open-telemetry/opentelemetry-specification/blob/fd43145dde7e5192ebc59a20992d98a3e6af5553/oteps/4430-span-event-api-deprecation-plan.md diff --git a/static/refcache.json b/static/refcache.json index ea248b79dfd1..aa3d944c3add 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -7263,6 +7263,10 @@ "StatusCode": 206, "LastSeen": "2026-02-25T09:58:49.771624997Z" }, + "https://github.com/open-telemetry/community/issues/3312": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:09:03.478944533Z" + }, "https://github.com/open-telemetry/community/issues/828": { "StatusCode": 206, "LastSeen": "2026-02-25T09:53:15.040902409Z" @@ -13959,6 +13963,10 @@ "StatusCode": 206, "LastSeen": "2026-02-24T07:00:17.885904-05:00" }, + "https://github.com/open-telemetry/opentelemetry-specification/blob/fd43145dde7e5192ebc59a20992d98a3e6af5553/oteps/4430-span-event-api-deprecation-plan.md": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:08:58.24078157Z" + }, "https://github.com/open-telemetry/opentelemetry-specification/blob/main/development/trace/zpages.md": { "StatusCode": 206, "LastSeen": "2026-03-10T09:52:20.223243255Z" @@ -14055,6 +14063,10 @@ "StatusCode": 206, "LastSeen": "2026-03-12T10:02:29.131580962Z" }, + "https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md": { + "StatusCode": 206, + "LastSeen": "2026-03-11T20:16:30.474103296Z" + }, "https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event": { "StatusCode": 206, "LastSeen": "2026-03-02T09:52:51.193831593Z" @@ -14063,6 +14075,10 @@ "StatusCode": 206, "LastSeen": "2026-02-27T09:51:55.87202297Z" }, + "https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/trace/api.md": { + "StatusCode": 206, + "LastSeen": "2026-03-11T20:16:27.085359886Z" + }, "https://github.com/open-telemetry/opentelemetry-specification/blob/v1.42.0/specification/document-status.md": { "StatusCode": 206, "LastSeen": "2026-03-12T10:02:23.282878635Z" @@ -14215,10 +14231,18 @@ "StatusCode": 206, "LastSeen": "2026-03-10T09:52:37.469361095Z" }, + "https://github.com/open-telemetry/opentelemetry-specification/pull/4612": { + "StatusCode": 206, + "LastSeen": "2026-03-09T10:39:28.505227175Z" + }, "https://github.com/open-telemetry/opentelemetry-specification/pull/4738": { "StatusCode": 206, "LastSeen": "2026-02-26T16:10:50.893159-06:00" }, + "https://github.com/open-telemetry/opentelemetry-specification/pull/4886": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:09:07.622722159Z" + }, "https://github.com/open-telemetry/opentelemetry-specification/tree/main/oteps/#readme": { "StatusCode": 206, "LastSeen": "2026-02-25T09:53:56.625250053Z" @@ -15395,6 +15419,14 @@ "StatusCode": 206, "LastSeen": "2026-03-10T09:55:34.535199875Z" }, + "https://github.com/open-telemetry/semantic-conventions/pull/3226": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:09:16.498831887Z" + }, + "https://github.com/open-telemetry/semantic-conventions/pull/3256": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:09:12.021643516Z" + }, "https://github.com/open-telemetry/semantic-conventions/pull/3267": { "StatusCode": 206, "LastSeen": "2026-03-10T09:56:41.724130534Z" @@ -15407,6 +15439,10 @@ "StatusCode": 206, "LastSeen": "2026-03-10T09:56:17.663525526Z" }, + "https://github.com/open-telemetry/semantic-conventions/pull/3311": { + "StatusCode": 206, + "LastSeen": "2026-03-05T21:09:22.153672633Z" + }, "https://github.com/open-telemetry/semantic-conventions/pull/3317": { "StatusCode": 206, "LastSeen": "2026-03-10T09:55:59.078480488Z"