48.9k
OpenTelemetry semantic conventions are the standardized names and meanings for telemetry attributes, such as http.request.method, db.system.name, and service.name, so that data from any instrumented service stays portable and queryable across tools. The OpenTelemetry project declared its first conventions, for HTTP, stable in v1.23.0 (November 2023); the registry has been growing signal by signal since.
TL;DR
- Semantic conventions are OpenTelemetry's shared vocabulary: agreed attribute names, values, and units (
http.request.method,db.system.name,service.name) that every SDK, instrumentation library, and backend can rely on. - Stability arrived in waves: HTTP conventions became stable in v1.23.0 (November 2023), database conventions in v1.33.0 (2025), while the GenAI conventions remain at
Developmentstatus in 2026. - The registry groups conventions by what they describe: resources, spans, metrics, and logs/events, each with its own attribute sets.
- Version migration has explicit mechanics: a
schema_urlon every resource and scope, plusOTEL_SEMCONV_STABILITY_OPT_INdup modes that emit old and new names side by side. - Downstream, conventions become columns. Consistent attribute names are what make one query work across every service you run.
What are OpenTelemetry semantic conventions?
OpenTelemetry semantic conventions are a published registry of standardized attribute names, allowed values, and units for telemetry data. They define what a piece of telemetry must be called (http.request.method rather than method, httpMethod, or verb) so traces, metrics, and logs from different services and languages describe the same thing the same way.
Without a convention, five teams instrument an HTTP status code five ways: status, code, http_status, statusCode, response.status. Every dashboard, alert, and query then needs per-service special cases. The semantic conventions registry removes that negotiation: one name, one type, one meaning, maintained as YAML definitions in the open-telemetry/semantic-conventions repository and versioned with each release (v1.43.0 as of July 2026). Official OpenTelemetry SDKs and auto-instrumentation libraries emit these names by default, which is why telemetry from a Go service and a Java service can land in the same backend and answer the same query.
Why do semantic conventions matter in observability?
Semantic conventions matter because they make telemetry portable and queryable. Consistent attribute names mean the same backend, dashboards, and queries work across every service, no matter which team or language produced the data. They also decouple instrumentation from vendors: data instrumented once can move between OpenTelemetry-compatible backends without re-instrumenting.
The effect is easiest to see at the storage layer. In a columnar store, http.response.status_code becomes one column populated by every service, so "error rate by service for the last hour" is a single GROUP BY with no per-service field mapping or translation layer. Turning conventions into a database schema is a design exercise precisely because the conventions do the hard naming work up front.
The industry has consolidated on this vocabulary. Elastic began converging its Elastic Common Schema with the OpenTelemetry conventions in 2023, which contributed the url.* namespace used in the stable HTTP conventions. Cross-service views like distributed traces depend on it: a trace spanning twelve services is only readable because all twelve agree on what a span attribute means.
How is the semantic conventions registry organized?
The registry is organized by what the telemetry describes, split into resource, span, metric, and log/event conventions. Domain namespaces such as http.*, db.*, and k8s.* cut across all four groups.
| Convention group | What it describes | Example attributes | Question it answers |
|---|---|---|---|
| Resource | The entity emitting telemetry, set once per process | service.name, service.version, k8s.pod.name | Which deployment produced this? |
| Span | One timed operation inside a request | http.request.method, db.system.name, db.query.text | What did this operation do? |
| Metric | Instrument names, units, and dimensions | http.server.request.duration, db.client.operation.duration | What is p99 latency per route? |
| Log / event | Log records and structured events | exception.type, exception.message, exception.stacktrace | What error accompanied the failure? |
The same request produces attributes from several groups at once. A schema-level OTLP fragment:
{
"resource": {
"attributes": {
"service.name": "checkout",
"service.version": "2.14.0"
},
"schemaUrl": "https://opentelemetry.io/schemas/1.43.0"
},
"span": {
"name": "GET /api/carts/{cartId}",
"attributes": {
"http.request.method": "GET",
"http.route": "/api/carts/{cartId}",
"http.response.status_code": 200,
"server.address": "cart.internal"
}
}
}Metric conventions fix units as well as names: http.server.request.duration is a histogram measured in seconds, which is what makes OpenTelemetry histograms aggregatable across services.
Are OpenTelemetry semantic conventions stable?
Partly. Each convention carries one of three stability statuses (Development, Release Candidate, or Stable), and only Stable names are guaranteed not to change. HTTP conventions have been stable since v1.23.0 (November 2023) and database conventions since v1.33.0 (2025), while the GenAI conventions remain entirely at Development status in 2026.
The database stabilization shows what graduation looks like in practice. v1.33.0 renamed db.system to db.system.name, restructured its values into a vendor.product pattern, and changed the recommended span name. All three are breaking changes, which is exactly why they landed before the conventions were declared stable.
At the other end, OpenTelemetry's GenAI conventions, the gen_ai.* namespace for LLM and agent telemetry, went through three attribute renames in a single 2026 release cycle and moved to a dedicated repository. Treat the status field as load-bearing: build long-lived dashboards and schemas on stable names, and expect Development names to change under you.
How do you handle semantic convention version changes?
OpenTelemetry handles convention changes through telemetry schemas: every resource and instrumentation scope can carry a schema_url (for example https://opentelemetry.io/schemas/1.43.0) declaring which version of the conventions the data follows. Published schema files describe the exact transformations, mostly renames, between any two versions, so consumers can translate old data to new names.
The Telemetry Schemas specification defines that translation contract. For the migrations that hurt, OpenTelemetry adds a dual-emission mechanism. During the HTTP and database stabilizations, instrumentation libraries were required to support the OTEL_SEMCONV_STABILITY_OPT_IN environment variable: setting it to http/dup or database/dup emits both the old and the new attribute names side by side, so dashboards and alerts keep working while queries are updated.
A migration sequence that follows the design:
- Record which conventions version each SDK and instrumentation library emits; the
schema_urlstates it. - Switch to
dupmode so both attribute vocabularies flow. - Update every query, dashboard, and alert that references a renamed attribute (for example
http.method→http.request.method). - Opt in to new-only emission and drop the duplicates.
Automatic translation is still thin on the ground (a schema transformation processor for the OpenTelemetry Collector exists in opentelemetry-collector-contrib but remains in development), so the dup-mode rollout is the reliable path.
Semantic conventions in ClickStack
ClickStack is the ClickHouse observability stack: ClickHouse for storage and query, HyperDX as the UI, and a bundled OpenTelemetry collector for ingestion. Because it is OTel-native, the conventions above map directly onto its tables. service.name becomes the ServiceName column, span attributes land in a queryable attributes map, and any convention-named field can be filtered or aggregated without pre-declaring it.
A cross-service latency question is one query shape because every service used the same names:
SELECT
ServiceName,
SpanAttributes['http.route'] AS route,
quantile(0.95)(Duration) AS p95
FROM otel_traces
WHERE SpanAttributes['http.request.method'] = 'GET'
AND Timestamp > now() - INTERVAL 1 HOUR
GROUP BY ServiceName, route
ORDER BY p95 DESCFor high-traffic attributes, promoting convention-named fields to typed columns tightens compression and speeds filters; the ClickStack documentation covers the default schema.
FAQ
What are the semantic conventions for HTTP spans?
The stable HTTP span conventions require http.request.method and name server spans {method} {route}, for example GET /api/carts/{cartId}. Core attributes include http.response.status_code, http.route, url.path, server.address, and error.type on failures. Client and server spans share the vocabulary but differ in which attributes are required.
How do I apply semantic conventions to my instrumentation?
Use official OpenTelemetry SDKs and auto-instrumentation libraries first; they emit convention names by default. For manual spans, take attribute names from the registry instead of inventing them, and import your language's semantic-conventions constants package so renames arrive as library updates. Reserve custom names for concepts the registry genuinely does not cover.
What are the GenAI semantic conventions in OpenTelemetry?
The GenAI conventions are the gen_ai.* namespace describing LLM calls and agent operations as spans, events, and metrics: gen_ai.provider.name and gen_ai.operation.name are required, with token counts in gen_ai.usage.*. They live in the dedicated semantic-conventions-genai repository since 2026 and every attribute is still Development status.
What is the difference between resource attributes and span attributes?
Resource attributes describe the entity producing telemetry (service.name, service.version, k8s.pod.name) and are set once per process, attaching to every signal it emits. Span attributes describe one operation (http.request.method, db.query.text) and are set per span. Backends typically store resources and spans in separate column groups for this reason.
To see convention-named telemetry as queryable columns, try ClickStack, the open-source, OpenTelemetry-native observability stack built on ClickHouse.
