OpenTelemetry Semantic Conventions Explained

Semantic conventions are OpenTelemetry’s specification for what telemetry attributes should be called and what values they should hold. Instead of every language, framework, or team inventing its own name for “the HTTP method of this request” or “which database system this span talks to,” OpenTelemetry defines a single canonical name — http.request.method, db.system.name — that every conformant instrumentation library is expected to use.

Without this, telemetry from a Java service and a Python service would describe the same concept with different field names, making cross-service dashboards, queries, and correlation far harder than they need to be.

Why it matters

• Makes telemetry comparable across languages and frameworks. A trace produced by an auto-instrumented Java service and one produced by a hand-instrumented Go service use the same attribute names for the same concepts, so they can be queried and joined together.
• Makes dashboards and queries portable across backends. A query built against http.response.status_code works the same way whether the data lands in Prometheus, Tempo, or a commercial APM tool, because the attribute name isn’t backend-specific.
• Reduces vendor lock-in at the query layer. Even after switching backends, existing alerts and dashboards built on semantic-convention field names keep working, since the underlying data model didn’t change.
• Gives instrumentation authors a stable contract. Library maintainers writing instrumentation for a new framework don’t have to guess at naming — they follow the spec for that domain (HTTP, database, messaging, RPC, and so on).

Key concepts

• Attributes are namespaced by domain. Names use dot-separated namespaces such as http.*, db.*, network.*, k8s.*, and gen_ai.*, each covering a specific technical domain with its own set of required and recommended attributes.
• Resource attributes vs. span/metric attributes. Resource attributes (service.name, k8s.pod.name, cloud.provider) describe the entity producing the telemetry and are attached once per process; span and metric attributes describe the specific operation being recorded.
• Conventions carry an explicit stability level. Each convention area is marked Development, Alpha, Beta, or Stable in the specification. HTTP conventions were the first to reach Stable status; database conventions are stable for most systems but still mixed for a few edge cases; newer areas like gen_ai (covering LLM calls) remain in active development and can still change.
• Breaking renames happen during stabilization — and are opt-in. The HTTP conventions’ move to Stable renamed several fields (for example http.method became http.request.method). Because this breaks existing dashboards, SDKs gate the new names behind the OTEL_SEMCONV_STABILITY_OPT_IN environment variable, which can be set to emit only the new names, or emit both old and new side by side during a transition.
• The specification, not any single SDK, is the source of truth. Semantic conventions are defined centrally in the OpenTelemetry specification and consumed by every language SDK and by instrumentation libraries, which is what keeps them consistent across the ecosystem.

Because this specification is still actively evolving in several domains, it’s worth checking a convention’s current stability level before building critical dashboards or alerts on it — a Development-stage attribute name can still change, while a Stable one is locked in except for future deprecation. Both the OpenTelemetry SDKs and the Collector rely on these names being consistent to do their job — the Collector’s attributes and transform processors, for instance, are frequently used to normalize telemetry from non-OTel sources onto these same conventions before export.