OpenTelemetry semantic conventions are the standard names and values for telemetry attributes, metrics and spans, such as http.request.method or service.name, so data from any library or language means the same thing.
Why they exist
Without shared names, one library records method, another http_method, a third verb. A query for "all POST requests" has to know every spelling, and a dashboard built for one service breaks on the next. Semantic conventions fix the names, the value formats and the units, so any backend can read data from any instrumented library the same way.
What they cover
| Area | Examples |
|---|---|
| Resource attributes: who produced the data | service.name, service.version, deployment.environment.name, host.name, k8s.pod.name |
| HTTP | http.request.method, http.route, http.response.status_code, url.path |
| Databases | db.system.name, db.operation.name, db.collection.name, db.query.text |
| Messaging | messaging.system, messaging.destination.name, messaging.operation.type |
| Errors | error.type, exception.type, exception.message |
| Metrics | http.server.request.duration in seconds, as a histogram |
They also define span names and kinds. An HTTP server span is named {method} {route}, such as GET /orders/{id}, and has kind SERVER. Conventions for metrics say which attributes to attach, and they stick to bounded ones such as http.route rather than url.path, which keeps cardinality under control.
service.name is the one attribute every service should set, usually through OTEL_SERVICE_NAME. Without it, data arrives as unknown_service and services cannot be told apart.
Renamed attributes
The conventions changed as they stabilised, and older instrumentation still emits the earlier names. The HTTP conventions, stable since 2023, renamed several common attributes:
| Older name | Current name |
|---|---|
http.method | http.request.method |
http.status_code | http.response.status_code |
http.target, http.url | url.path and url.query, url.full |
net.peer.name | server.address |
Instrumentation that supports both lets you choose with OTEL_SEMCONV_STABILITY_OPT_IN: http for the new names only, http/dup for both while dashboards and alerts migrate. If a query that worked last month returns nothing after a dependency upgrade, a renamed attribute is a likely cause.
Stability levels
Each group of conventions carries a stability level. Stable conventions, such as HTTP and the core resource attributes, will not be renamed. Development conventions can still change, so instrumentation that emits them may rename attributes in a minor release. Before you build alerts on an attribute, check its status in the conventions; for anything still in development, pin the instrumentation version and read its changelog before upgrading.
A schema_url on resources and scopes records which version of the conventions the data follows, so a backend or Collector can translate between versions.
Your own attributes
For data the conventions do not cover, use a namespace you own, such as app. or your company name: app.order.value, app.customer.plan. Do not invent names inside an OpenTelemetry namespace like http. or db., since a future convention may define the same name with a different meaning. Use lowercase, dot-separated words and snake_case within a segment, as the conventions do.