Practical OpenTelemetry — Part 3: The Spec, Signals, and Stability

If Part 2 was the why, this is the what. Chapter 3 of Practical OpenTelemetry lays out the project’s anatomy: the specification, the four signals, the API/SDK split, semantic conventions, and the stability promises that let an entire industry build on top of it.

This is the chapter to get right before the hands-on parts, because every later decision — what to instrument, how to name it, whether to use the SDK directly — traces back to these fundamentals.

The Specification: A Contract, Not a Codebase

OpenTelemetry is, at its core, a specification — a living document that captures the requirements any component must meet to be considered compliant. The actual code (SDKs in a dozen languages, the Collector) is an implementation of that spec.

Two things about the spec are worth internalizing:

Stability is a first-class property of the spec — at two different granularities. Individual spec documents carry a status: No explicit status (equivalent to Experimental), Experimental (breaking changes allowed), Stable (no breaking changes), or Deprecated (editorial changes only) — plus an orthogonal feature-freeze flag that can attach to a document at any of those stages, signaling maintainers aren’t accepting new features to it so the community can focus elsewhere. Zoom out one level and a whole signal (Tracing, Metrics, Logs, Baggage) has its own, slightly different life cycle: Experimental (alpha/beta/RC — breaking changes can land on a minor version bump) → Stable (no breaking changes without a major version bump) → Deprecated (once a replacement signal reaches Stable) → Removed (a breaking change, so it needs a major version bump). This is how the project ships new signals without destabilizing existing users: a signal moving through its own life cycle never forces stable signals to move with it.

Big changes go through OTEPs. Small changes are ordinary GitHub issues and PRs. Larger, cross-language or cross-component changes require an OpenTelemetry Enhancement Proposal (OTEP) — modeled explicitly on the Kubernetes Enhancement Proposal process (and the Rust RFC process). This is how major architectural decisions get standardized rather than forked: OTEP PR #111, for instance, is the real proposal that standardized automatic resource detection — the mechanism Part 4 covers in depth — by taking pre-existing, incompatible approaches from OpenCensus and individual language SDKs and proposing one common design. Once an OTEP is approved and integrated into the specification, the process doesn’t stop at the paper stage: issues get created in every component the proposal affects, and as each one lands, its compliance status is updated against a specific spec version — the same document-status vocabulary from the diagram above.

The version that matters historically: spec v1.0.0 shipped in February 2021, marking Tracing, Context, and Baggage stable. The long-term support policy is the kind of boring promise that makes boring enterprise adoption possible: no 2.x is planned, and if one ever ships, stable APIs are supported for at least three years, SDKs and contrib packages for at least one.

Four Signals, One Context

OpenTelemetry organizes telemetry into signals, each covering an observability area:

• Traces — the path of a single transaction across services, built from spans
• Metrics — aggregated measurements over time (the oldest signal)
• Logs — the rawest form of telemetry (the newest addition to the spec)
• Baggage — user-defined key-value pairs propagated alongside requests

Binding them together is a shared context subsystem that propagates data across a distributed transaction, enabling the cross-service correlation that Part 1 argued is the whole point.

One design decision deserves emphasis, because it explains a lot of the project’s stability: each signal is structured as four separate packages:

• API — the public interfaces; application and library code depends only on this
• Semantic conventions — standard attribute names, auto-generated from YAML in the spec repo
• SDK — the reference implementation, with plugin hooks for exporters and processors
• Contrib — community-maintained instrumentation and exporters

The book’s tip is pointed: minimize SDK touch points in your applications. Instrumentation that only touches the API survives SDK upgrades, backend changes, and even vendor migrations. The SDK is a deployment-time concern, not a code-time one.

The No-Op Guarantee

One subtle but crucial property: APIs return no-op implementations when no SDK is configured. This is what makes “instrument once” safe for library authors — a library can be fully instrumented, and users who never configure OpenTelemetry pay nothing and break nothing. The instrumented code simply does nothing until an SDK arrives at runtime.

The runtime guidelines flow from the same defensive philosophy: no unhandled exceptions, safe defaults when misused, low overhead, never block applications, never consume unbounded memory. A telemetry library that can take down the application it’s observing is worse than useless.

Semantic Conventions: The Naming Problem, Solved by YAML

Part 2 mentioned the naming problem (region vs cloud.region vs data_center). The solution is semantic conventions: a set of standard keys and values for describing telemetry across signals and languages. The critical implementation detail: conventions are defined in YAML files in the spec repository, and language constants are auto-generated from them. Go, Java, and Python can’t drift apart because they’re all compiled from the same source.

The most important conventions to know:

Resource Conventions

Resource conventions identify who produced the telemetry:

• service.name — required; unique within a namespace; identical across replicas
• service.namespace — groups related services (team, project)
• service.instance.id — one specific replica
• service.version — the running version
• Plus environment groups: cloud.*, container.*, host.*, k8s.*, process.*

If service.name is missing, the SDK defaults to unknown_service:java — a real signal you’ve misconfigured something. In Java, resource conventions ship as AttributeKey constants in a ResourceAttributes class, so identifying a producer looks like this — real code from the book, a running example (“lemonade-stand” / “juice-service”) it returns to across several chapters:

Resource resource = Resource.create(
    Attributes.of(
        ResourceAttributes.SERVICE_NAME, "juice-service",
        ResourceAttributes.SERVICE_NAMESPACE, "lemonade-stand"));

Tracing Conventions

Tracing conventions govern span attributes. One naming rule matters more than the rest: server span names must not include URL parameters. /api/customer/1763/pet/3 fragments spans into useless statistical groups. The instrumentation extracts path variables instead: /api/customer/{customer_id}/pet/{pet_id}, so every call to the same operation shares a statistically significant name. High-cardinality names kill both cost and usability. Applying a convention to the current span in Java looks like this:

Span span = Span.current();
span.setAttribute(
    SemanticAttributes.NET_PEER_NAME,
    "my-dependency.example.com");

Metric Conventions

Metric conventions share the same philosophy with an extra rule: metric names have global scope. http.client.duration means the same thing regardless of client library. Units live in the data model, not the name (http.client.duration — never duration_ms). And no pluralization unless the value is genuinely countable (errors, not error). The book’s own anti-pattern example is worth keeping in mind before you name your first custom metric: prod.my-svc.okhttp.duration bakes environment and service identity into the metric name itself, which means every environment and every service invents its own metric — exactly the fragmentation semantic conventions exist to prevent. Environment and service identity belong on the Resource, not the metric name. (Metric conventions are, at time of writing, the least mature of the three — not yet part of the opentelemetry-semconv package.)

Signals at a Glance

The book’s advice for choosing between signals is the same advice repeated throughout the series: use the right signal for the right purpose.

The chapter closes with telemetry schemas — an experimental mechanism (schema_url) that lets semantic conventions evolve without breaking portability, by describing the transformations needed to convert telemetry between versions. It’s the project acknowledging something mature standards do: naming will need to change someday, and we need a plan for when it does.

Next: Practical OpenTelemetry — Part 4: Auto-Instrumentation, Zero Code Changes — the Java agent, bytecode injection, and how to get spans, metrics, and context propagation without touching application code.

References

• Practical OpenTelemetry (Apress, 2023) — Daniel Gomez Blanco
• OpenTelemetry Specification
• OpenTelemetry Semantic Conventions
• OpenTelemetry Project Status