Semantic conventions are the standardized names, types, and meanings for common attributes — the reason an HTTP status code looks the same whether it came from a Java service or a Python one.
The problem conventions solve
Without a shared vocabulary, every team (and every library author) invents their own attribute names: status_code, httpStatus, http_status_code, response_code — all describing the same thing. Dashboards, alerts, and correlation queries built against one naming scheme silently break against another. Semantic conventions fix this by defining, for each domain (HTTP, databases, messaging, cloud providers, RPC, and more), the exact attribute key, its type, and its meaning — so any tool built against the convention works with telemetry from any compliant SDK or instrumentation library.
Resource conventions
Resource attributes describe the entity emitting telemetry and are defined once per process:
| Attribute | Meaning |
|---|---|
service.name | Logical name of the service — the single most important attribute in the whole system. |
service.version | Deployed version, useful for correlating regressions with releases. |
deployment.environment.name | e.g. production, staging. |
host.name | Hostname of the machine running the process. |
cloud.provider / cloud.region | Cloud metadata, often auto-detected by SDK resource detectors. |
Span attribute conventions
Domain-specific conventions cover the attributes you'd expect on spans for that domain:
| Domain | Example attributes |
|---|---|
| HTTP | http.request.method, http.response.status_code, url.path |
| Database | db.system.name, db.query.text, db.namespace |
| Messaging | messaging.system, messaging.destination.name, messaging.operation.type |
| RPC | rpc.system, rpc.service, rpc.method |
span.setAttributes({
'http.request.method': 'POST',
'url.path': '/checkout',
'http.response.status_code': 200,
'db.system.name': 'postgresql',
});Stability levels
Semantic conventions are versioned and marked with a maturity level, because getting a widely-used name wrong and having to change it later breaks dashboards across the ecosystem:
- Development — actively being defined; expect breaking changes.
- Release Candidate — largely settled; only clarifications expected.
- Stable — guaranteed backward compatible going forward.
Early OpenTelemetry HTTP conventions used names like http.method and http.status_code; the stabilized conventions renamed these to http.request.method and http.response.status_code. If you're following an older tutorial or blog post, check current attribute names against the live semantic conventions registry before copying them.
Schema URLs and versioning
Telemetry can be tagged with a Schema URL identifying exactly which version of the semantic conventions it follows. This lets backends and the Collector apply automatic translation between schema versions — so a service still emitting an older attribute name can be translated to the current name without requiring every service to upgrade in lockstep.
When to add your own attributes
Semantic conventions cover common, cross-cutting concerns — they will never cover your specific business domain. For anything domain-specific (an order ID, a discount code, a feature flag value), define your own attributes, but follow the same discipline the conventions use:
- Use a namespaced prefix specific to your organization or domain, e.g.
acmecorp.order.id, to avoid colliding with future official conventions. - Keep names consistent across every service that touches the same concept.
- Document them somewhere your whole team can find, the same way the official registry documents standard ones.
Follow official semantic conventions for anything they define (HTTP, DB, messaging, resource identity) so your telemetry works with any tool out of the box. Reserve custom attributes for things genuinely specific to your business.