OpenTelemetry Semantic Conventions
Semantic conventions standardize attribute names and values across telemetry — http.url, db.system, messaging.destination — making instrumentation from different libraries comparable and queryable.
Definition
Semantic conventions are a versioned specification of attribute names, value types, and enumerated values for telemetry across domains — HTTP, database, messaging, runtime. Instrumentation emitting convention-compliant attributes becomes comparable across services and queryable fleet-wide without per-team vocabulary mapping.
Context and scope
Consumed by library authors, telemetry platform vendors, and app teams defining custom namespaces. Versioned specs with stability guarantees.
Common misconceptions
- Conventions are optional naming suggestions — they are the interoperability layer; ignoring them means your telemetry speaks a private dialect
- Adopting them requires OpenTelemetry — the conventions are consumable by any system; many vendors and libraries map them to their own attribute sets
- Conventions freeze forever — they version with stability phases; early adoption rides development status and tracks renames
Anti-patterns
- Inventing attribute names per service and losing fleet-wide queries such as all slow postgres operations
- Mixing convention versions and querying renamed attributes that silently return nothing
- Putting company-specific values in reserved namespaces and colliding with future standard attributes
Related concepts
Related examples
Authoritative source
What it is
Two instrumentations both record the database name. One calls it db, another database, a third db_name. Every query becomes three queries. Conventions collapse these into one agreed vocabulary with specified types and expected values.
How it works
The spec defines namespaces per domain — http, db, messaging, faas, and others — with attribute names, value types, and enumerated values (db.system: postgresql, mysql). Instrumentation libraries emit them; collectors transform legacy formats into them; backends index them as first-class dimensions. Custom namespaces extend without collision.
When to follow
From project start, and when integrating any new instrumentation library. Define your internal extension policy — custom namespace, documented attributes, reviewed vocabulary — so domain concepts get the same discipline.
Pitfalls
Version transitions rename attributes; queries pinned to old names silently return empty. Deviating “just slightly” — status_code versus status.code — recreates the dialect problem the conventions exist to kill. Attribute values are as standardized as names: free-text db.system values defeat enumerations built for matching.