Deprecating Span Events API

Why It Matters

Consolidating events under the Logs API simplifies instrumentation guidance and accelerates feature evolution, directly affecting developers, operators, and observability vendors.

Key Takeaways

• Span.AddEvent and RecordException will be deprecated
• New events should be emitted via the Logs API
• Existing span events stay visible through a compatibility layer
• Observability backends must support ingestion of log‑based events
• Instrumentation libraries will migrate to log‑based events soon

Pulse Analysis

OpenTelemetry has long offered two parallel mechanisms for attaching contextual information to traces: span‑level events and log‑based events. While both serve similar purposes, the coexistence has created fragmented guidance for library authors and operational overhead for users who must understand dual export paths. By treating events as structured logs correlated through context, the ecosystem gains a single, extensible model that aligns with emerging observability standards and simplifies schema evolution.

The deprecation plan, outlined in OTEP 4430, targets the API surface rather than the data itself. Methods such as Span.AddEvent and Span.RecordException will be marked deprecated, and SDKs will promote the Logs API as the primary entry point for new events. A compatibility shim ensures that log‑based records can still surface in traditional span‑centric views, protecting existing dashboards and alerting configurations. This approach preserves backward compatibility while encouraging a gradual migration, allowing operators to upgrade without immediate code changes.

For developers and vendors, the shift signals a strategic pivot toward richer, more flexible event metadata and unified export pipelines. Instrumentation packages will soon default to log‑based emission, and semantic convention authors are urged to document events as log records. Observability platforms must adapt ingestion pipelines to handle log‑based events alongside traces and metrics, ensuring seamless correlation. Ultimately, the move streamlines the OpenTelemetry stack, reduces maintenance burden, and positions the project for faster innovation in the rapidly evolving observability landscape.