What are OpenTelemetry's semantic conventions, why are they versioned and stabilised separately from the SDKs, and how would you migrate a fleet across a breaking attribute rename such as http.method becoming http.request.method?
answer
- agreed key names = cross-library queryability
- conventions version separately, stabilise per area
- http.method → http.request.method rename
- opt-in switch: old / dual / new
- own attributes in your own namespace
basics
~20 sSemantic conventions are the agreed names and value shapes for attributes — the reason telemetry from unrelated libraries is queryable together. They version independently, stabilising area by area. Breaking renames are migrated with a dual-emit opt-in: emit old and new, cut dashboards over, then drop the old.
solid answer
~50 sA trace is only portable because everyone agrees the server address goes in `server.address` and the HTTP status in `http.response.status_code`. Semantic conventions are that registry, plus the resource attributes (`service.name`, `service.version`) and metric names. They ship on their own release train and stabilise **per area**: HTTP first, then others, with the rest still marked experimental — so 'OpenTelemetry is stable' is never a single answer, it is per signal and per convention area. Stabilisation forced real renames — `http.method` → `http.request.method`, `net.peer.name` → `server.address`. The migration mechanism is an opt-in environment variable per area with three states: old only (the default while a convention is young), **both** (dual emit), and new only. The sequence is: upgrade instrumentation with dual emit on, port dashboards, alerts and saved queries to the new names, verify, then flip to new-only and remove the duplicates. Spans also carry a schema URL naming the convention version, which is what lets tooling translate mechanically.
go deeper
Know that conventions are the standard attribute names that make telemetry from different libraries comparable, and that custom keys go in your own namespace.
Explain the separate versioning and per-area stability, and name at least one real rename and the dual-emit switch.
Own the migration: dual emit, port queries, verify, flip, delete — plus schema URLs and the cardinality constraint on metric-bound attributes.
Treat the vocabulary as a governed asset: a company namespace with owners, upgrades scheduled against convention releases, and dual-emit windows tracked as debt.
## The problem conventions solve Telemetry is only useful if it can be queried without knowing who produced it. 'Show me error rate by remote host across every client library in the fleet' works when all of them write the host into the same attribute key with the same meaning, and fails the moment one writes `peer.host`, another `net.host`, and a third `hostname`. Semantic conventions are the specification of those keys: their names, types, value shapes, requirement levels (required / recommended / opt-in), and the metric names derived from them. They cover more than spans: resource attributes that identify the emitting entity, metric names and units, log record fields, and per-domain attribute sets for HTTP, databases, messaging, RPC, cloud platforms, runtimes and more. ## Why a separate release train An SDK's API can be stable while the vocabulary is still being argued about, and the two evolve at very different speeds. Decoupling them means the SDK can promise compatibility while conventions mature area by area. It also means the honest answer to 'is it stable?' is a matrix: signal stability (tracing and metrics long stable, logs newer) crossed with convention-area stability (HTTP stable, several others still experimental). An experimental area may rename attributes between releases; a stable one may not without the migration process below. ## Namespacing rules worth knowing Keys are dotted namespaces (`http.request.method`, `db.query.text`), lowercase, with the general shape going from broad to specific. The reserved top-level namespaces belong to the project; **your own attributes must live in your own namespace** (`acme.tenant.tier`), never inside `http.` or `db.`, because the project may later define that exact key with a different meaning and your data will silently collide. The other rule with teeth: attributes that become metric dimensions must be low-cardinality. A user id is a fine span attribute and a catastrophic metric label — this is why conventions distinguish route templates from concrete paths. ## Migrating a breaking rename Renames like `http.method` → `http.request.method` or `http.status_code` → `http.response.status_code` break every dashboard and alert that referenced the old key. The mechanism instrumentation provides is an opt-in switch, scoped per convention area, with three positions: 1. **Old only** — the pre-stabilisation behaviour, the default during a deprecation window. 2. **Dual emit** — both old and new keys are written on every span. Costs bytes and storage, is meant to be temporary. 3. **New only** — the end state. A fleet migration therefore looks like: upgrade instrumentation everywhere with dual emit enabled; port dashboards, alerts, saved queries and any downstream consumers to the new keys; verify both spellings agree in production for a bounded window; then flip services to new-only, oldest-first; finally delete the old queries. Treat 'dual emit still on' as a tracked debt item with an owner and a date — it is a migration state, not a configuration. ## Schema URLs Spans and metrics can carry a **schema URL** identifying the convention version their attributes conform to. Combined with published schema files that describe renames between versions, this allows a receiver or collector to translate old telemetry into current names mechanically. It only helps if instrumentation actually sets the schema URL and if your pipeline honours it, so treat it as an aid rather than a substitute for the migration above. ## What this means when you write your own instrumentation Check the registry before inventing a key — the odds are the concept already has a name. Use conventional keys with conventional meanings, and put anything genuinely yours under your company's namespace. Pin the convention version you targeted, and re-read it when you upgrade instrumentation, because that is where the surprises live.
- Why is dual emit deliberately temporary rather than a safe permanent setting?Every duplicated attribute is bytes on the wire, in the exporter's batch, and in the backend's index, on every span — a permanent tax for a transitional benefit. It also lets two spellings drift, so queries silently disagree depending on which key they use. Give it an owner and an exit date and treat lingering dual emit as debt.
- A team wants to add a custom attribute for their tenant tier. Where should it go and why not under an existing namespace?Under a company-owned namespace, e.g. acme.tenant.tier. Reserved namespaces belong to the specification, and if it later defines the same key with different semantics your data collides with no warning and no migration path. A private namespace also makes it obvious in review which attributes are yours to change.
saying these in an interview costs you the question
- Treating 'OpenTelemetry is stable' as one fact rather than per signal and per convention area
- Inventing attribute keys without checking the registry, or placing custom keys inside reserved namespaces
- Renaming attributes in production without dual emit and without porting dashboards first
- Leaving dual emit on permanently because it is convenient
- Using high-cardinality values in attributes destined to become metric dimensions