[blog] Deprecating Span Events API

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

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"