---
title: "OpenTelemetry semantic conventions explained"
date: "2026-07-29"
author: "Al Brown"
category: "Engineering"
excerpt: "OpenTelemetry semantic conventions standardize telemetry attribute names like http.request.method and db.system.name, so data from any service is portable and queryable across tools."
---

# OpenTelemetry semantic conventions explained

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](https://opentelemetry.io/blog/2023/http-conventions-declared-stable/) (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 `Development` status 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_url` on every resource and scope, plus `OTEL_SEMCONV_STABILITY_OPT_IN` dup 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](https://opentelemetry.io/docs/specs/semconv/) 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](/resources/engineering/what-is-distributed-tracing) 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:


```json
{
  "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](/resources/engineering/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](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/) `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](https://opentelemetry.io/docs/specs/otel/schemas/) 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:

1. Record which conventions version each SDK and instrumentation library emits; the `schema_url` states it.
2. Switch to `dup` mode so both attribute vocabularies flow.
3. Update every query, dashboard, and alert that references a renamed attribute (for example `http.method` → `http.request.method`).
4. 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](https://clickhouse.com/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:


```sql
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 DESC
```

For high-traffic attributes, promoting convention-named fields to typed columns tightens compression and speeds filters; the [ClickStack documentation](https://clickhouse.com/docs/clickstack/overview) covers the default schema.


## FAQ

### Question 1: 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.### Question 2: 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.### Question 3: 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.### Question 4: 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](https://clickhouse.com/clickstack), the open-source, OpenTelemetry-native observability stack built on ClickHouse.*