# OpenTelemetry Deprecates Span Events API in Favor of Log-Based Events

- Link: https://thestackobserver.com/opentelemetry-deprecates-span-events-api-in-favor-of-log-based-events/
- Published: 2026-03-20T08:19:49-04:00
- Author: Stackxx

**OpenTelemetry is deprecating the Span Events API**, marking a significant evolution
in how the observability standard handles event telemetry. The change aims to eliminate
confusion caused by having two overlapping event mechanisms — span events and log-
based events — and to establish a single, consistent approach for instrumenting 
application events across all OpenTelemetry language implementations.

## The Problem: Dual Event Pathways

Currently, OpenTelemetry offers two different ways to emit events correlated with
traces. Span events attach directly to spans through the Span API, while log-based
events correlate through context propagation and the Logging API. This duality created
decision paralysis for developers: which API should I use? Are they interchangeable?
Do backends handle them differently?

The inconsistency extended beyond developer experience. Different language SDKs 
implemented span events with varying feature sets — some supported attributes on
events, others didn’t. Log-based events, meanwhile, evolved rapidly with structured
logging, severity levels, and rich metadata support. The divergence meant that portable
instrumentation — a core OpenTelemetry goal — became harder to achieve.

The project’s guidance is now clear: **new code should write events as logs correlated
with the current span**. The older span events style will be phased out over time,
though existing data and span-event views will continue functioning during an extended
transition period designed to minimize disruption.

## Migration Path for Developers

For teams currently using span events, the migration involves several practical 
considerations:

 * **Audit existing instrumentation:** Review your codebase for span event usage,
   typically calls like `span.add_event()` or similar language-specific APIs.
 * **Identify migration candidates:** Not all span events need migration immediately.
   Events that are truly observability signals (debugging information, checkpoints,
   notifications) should transition to logs. Events that represent work units or
   operations might be better modeled as child spans.
 * **Update SDK versions:** Ensure you’re running OpenTelemetry SDK versions that
   support the log-based correlation API and context propagation.
 * **Verify downstream compatibility:** Confirm that your observability backend (
   Jaeger, Zipkin, commercial APM tools) handles log-based events appropriately.
   Most OTLP-compatible backends should require no changes.

Language implementations are expected to maintain backward compatibility during 
the deprecation period. Span events won’t disappear overnight — the project is following
a gradual deprecation path that gives teams runway to migrate without immediate 
breaking changes.

## Strategic Alignment with Log Standards

This deprecation aligns with OpenTelemetry’s broader goal of unifying telemetry 
signals under consistent APIs. The log-based approach leverages the OpenTelemetry
Logging API and OTLP LogData model, ensuring events benefit from the same semantic
conventions, batching optimizations, and transport reliability as application logs.

The unification also simplifies the collector pipeline. Rather than handling span
events as a special case in trace processing, events flow through standard log pipelines
where they can be filtered, sampled, and routed using familiar mechanisms. This 
consistency reduces operational complexity for platform teams managing observability
infrastructure.

## Industry Context and Future Direction

As the observability ecosystem matures, having a single event mechanism reduces 
cognitive overhead and simplifies instrumentation choices. Teams can focus on what
events to capture and when, rather than which API to use. The deprecation represents
OpenTelemetry’s commitment to API stability and developer experience — acknowledging
when early design decisions need refinement based on real-world usage patterns.

For organizations just beginning their OpenTelemetry adoption, this change simplifies
the decision matrix. Logging with automatic trace correlation is now the clear path
forward, backed by the full weight of the specification and community investment.

## Sources

 * OpenTelemetry Blog — “Deprecating Span Events API” (March 18, 2026)
 * OpenTelemetry Specification — Log Correlation with Spans
 * OpenTelemetry JavaScript SDK Migration Guide