OpenTelemetry Specification: The Standards Document That Governs Observability
Hook
This repository contains zero executable code, yet it controls how AWS, Google Cloud, Microsoft Azure, and every major observability vendor collects telemetry data. It's a standards document that moves like software.
Context
Before OpenTelemetry, observability was fragmented. If you instrumented your application with Zipkin for tracing, later switching to Jaeger meant rewriting instrumentation code. OpenTracing attempted to abstract tracing clients, while OpenCensus tackled metrics and tracing together, but neither achieved complete adoption. Enterprises were forced to choose vendors early and live with the consequences, or maintain multiple instrumentation libraries simultaneously.
The OpenTelemetry project emerged from merging OpenTracing and OpenCensus in 2019, but with a critical insight: the problem wasn't just competing implementations—it was the absence of a single, binding specification that all implementations agreed to follow. The opentelemetry-specification repository became that contract. Rather than letting each language SDK interpret telemetry concepts differently, this repo defines exactly how traces, metrics, and logs should behave across Java, Python, Go, JavaScript, and 40+ other implementations. It's IETF-style standardization applied to observability, complete with all the governance overhead that implies.
Technical Insight
The repository's architecture treats protocol specifications as version-controlled artifacts. Under the /specification directory, you'll find markdown files defining API surfaces, SDK behavior, semantic conventions, and wire protocols. The Makefile orchestrates validation—checking that schema definitions match actual YAML files, that version numbers follow semantic versioning rules, and that cross-references between documents remain intact.
What makes this fascinating is the compliance matrix. It's a publicly tracked spreadsheet linking specification requirements to implementation status across every SDK. When the spec defines that trace spans must support the SetStatus method, the matrix shows whether the Python SDK implemented it, whether Java's implementation is stable or experimental, and whether .NET even started work. This creates transparent accountability—vendors can't claim OpenTelemetry support without their gaps being publicly visible.
Here's how the spec defines trace context propagation, the mechanism that connects spans across service boundaries:
# From specification/context/api-propagators.md
TextMapPropagator:
description: |
Injects and extracts cross-cutting concern values as string key/value pairs
into carriers that travel in-band across process boundaries.
methods:
- name: Inject
parameters:
- name: context
type: Context
- name: carrier
type: TextMap
- name: setter
type: TextMapSetter
- name: Extract
parameters:
- name: context
type: Context
- name: carrier
type: TextMap
- name: getter
type: TextMapGetter
returns:
type: Context
This isn't pseudocode—it's the binding contract that every SDK must implement. When you call propagator.inject(context, headers) in Python, Go, or Rust, the behavior is specified here first. The SDK authors then translate this abstract API into idiomatic language constructs, but the semantics remain identical.
The semantic versioning enforcement is particularly clever. The specification itself has version numbers (currently 1.x stable for traces, mixed stability for metrics and logs), and the Makefile validates that changes to stable sections trigger major version bumps while experimental features can evolve freely. This allows the spec to include bleeding-edge experimental features like log message templates without forcing SDK implementers to support them immediately.
Governance happens through a multi-stakeholder approval process. Major changes require sign-off from approvers who work at competing companies—Splunk, Dynatrace, Microsoft, Grafana. This is design-by-committee by intention. The meeting notes reveal debates over minutiae like whether span event timestamps should use nanoseconds or microseconds, whether baggage items should have metadata, how to represent histogram bucket boundaries. These aren't academic questions—they determine whether backends can efficiently store telemetry and whether SDKs can implement features with acceptable performance.
The specification separates stability levels within the protocol itself. A single document might have stable sections (like basic span creation), experimental features (like span links with attributes), and deprecated elements (like the old Jaeger propagation format). SDK authors can selectively implement stable features first while ignoring experimental ones, avoiding the all-or-nothing adoption problem that plagued earlier standards.
Here's an example of how stability is encoded directly into specification text:
## Span Status
**Status:** Stable
Spans have an optional status consisting of StatusCode and Description.
### StatusCode
StatusCode is one of the following values:
- UNSET: The default status.
- OK: The operation completed successfully.
- ERROR: The operation contains an error.
**Note:** The ERROR status has **replaced** the legacy concept of "exception"
status from OpenTracing. [Legacy Compatibility]
The [Legacy Compatibility] tag links to another document explaining how to migrate from OpenTracing semantics, demonstrating how the spec handles backward compatibility concerns explicitly rather than leaving them to individual SDK maintainers.
Gotcha
The biggest limitation is inherent to the model: there's no reference implementation to validate the spec's feasibility before it's published. SDK authors discover ambiguities and edge cases only after attempting to build against the specification. When the spec says spans should support "arbitrary attributes," what are the performance implications at 100,000 spans per second? The Java team discovers memory pressure, the Go team hits garbage collection pauses, and the spec gets retroactively clarified with cardinality warnings—but only after implementations shipped and users hit production issues.
The multi-vendor governance creates design-by-committee pathologies. New features require consensus from competing companies, each with different customer bases and technical constraints. The result is incremental complexity accumulation—competing interests each get their feature included rather than making hard prioritization choices. The baggage propagation feature, for example, went through dozens of iterations as different vendors argued about size limits, metadata support, and security implications. The final design satisfies all stakeholders but is significantly more complex than any single vendor would have chosen independently.
Deprecation is nearly impossible once features reach stable status. Backward compatibility constraints mean bad early decisions live forever in the spec. The histogram bucket boundary debates revealed this clearly—the chosen design has known limitations for high-dynamic-range metrics, but changing it would break every backend that's already implemented the stable specification. The spec can add new histogram types (and did, with exponential histograms), but the original remains forever.
Verdict
Use if: You're building observability infrastructure that needs to interoperate with multiple backends, implementing an OpenTelemetry SDK for a new language, or working at a company where procurement requires "OpenTelemetry-compatible" vendors. The specification defines the contract you'll implement against or validate compliance with. Also essential if you're contributing to the OpenTelemetry ecosystem—you can't propose SDK changes without understanding how the spec governance works. Skip if: You're building internal-only instrumentation where you control both the collection and backend, or you need simple metrics collection where Prometheus exposition format or StatsD provides adequate functionality with far less complexity. The specification's multi-signal correlation and vendor neutrality only matter when you need that flexibility—otherwise you're paying governance overhead costs for features you'll never use. Skip entirely for greenfield projects where observability requirements aren't yet clear; implement something simple first and adopt OpenTelemetry later if multi-vendor support becomes necessary.