Semantic conventions

David Granzin By David Granzin

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

AreaExamples
Resource attributes: who produced the dataservice.name, service.version, deployment.environment.name, host.name, k8s.pod.name
HTTPhttp.request.method, http.route, http.response.status_code, url.path
Databasesdb.system.name, db.operation.name, db.collection.name, db.query.text
Messagingmessaging.system, messaging.destination.name, messaging.operation.type
Errorserror.type, exception.type, exception.message
Metricshttp.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 nameCurrent name
http.methodhttp.request.method
http.status_codehttp.response.status_code
http.target, http.urlurl.path and url.query, url.full
net.peer.nameserver.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.

Sources

今日、最初のトレースを。

SDKを追加し、OTLPエクスポーターをMapleに向ければトレースが届きます。

maple.dev:OpenTelemetryの上のオブザーバビリティ