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