Semantic Conventions

What are semantic conventions?

Semantic conventions (often shortened to semconv) are the part of the OpenTelemetry specification that defines what telemetry is called and what it means. Without them, one Java library would record status, a Python library http_code and a Go service response.status for the same HTTP status code. With them, every instrumented HTTP server reports http.response.status_code as an integer, and a single query works across your whole estate.

The conventions cover resource attributes (who produced the data), span attributes and span names, metric names and units, log and event attributes, and many technology domains such as HTTP, databases, messaging, RPC, cloud, Kubernetes, containers and generative AI.

Key attributes you will see everywhere

Attribute	Describes	Example value
service.name	Logical name of the service (resource)	checkout
service.version	Deployed version (resource)	2.14.1
deployment.environment.name	Environment (resource)	production
http.request.method	HTTP method	POST
http.response.status_code	HTTP response status	503
http.route	Matched route template, low cardinality	/orders/{id}
url.path	Actual request path	/orders/8812
server.address	Host name of the server	api.example.com
db.system.name	Database system	postgresql
db.query.text	Database query, sanitized	SELECT * FROM orders WHERE id = ?
k8s.pod.name	Kubernetes pod (resource)	checkout-7d9f-abc12

Metrics follow the same logic. The standard HTTP server latency metric is http.server.request.duration, a histogram in seconds, which lets any backend compute request rate, error rate and latency percentiles for every service without custom naming.

Example: one query for every service

Because every conforming HTTP server instrumentation records the same attributes, a single illustrative OQL query counts server errors per route across Java, Python and Go services alike:

fetch spans
| filter http.response.status_code >= 500
| summarize count(), by:{service.name, http.route}

Without shared conventions, the same question would need one query per language and framework, and every new service would require someone to update dashboards and alerts by hand.

Resource attributes vs. span attributes

OpenTelemetry distinguishes between the resource, the entity that produces telemetry, and the individual signal. Resource attributes such as service.name, host.name or cloud.region are set once per process and attached to every span, metric and log it emits. Span or data point attributes such as http.route describe a single operation. Keeping this separation clean avoids repeating the same metadata and makes correlation across signals reliable. If service.name is missing, SDKs fall back to unknown_service, which makes data hard to find, so always set it, for example via OTEL_SERVICE_NAME.

Beyond HTTP: messaging, RPC and generative AI

The same approach extends to other domains. Messaging conventions describe producers and consumers with attributes such as messaging.system and messaging.destination.name, RPC conventions cover gRPC calls, and the generative AI conventions define attributes for model calls, for example the requested model and input and output token counts. Several of these domains are still evolving, so check the stability level before you build long-lived dashboards on them.

Stability and migrations

Each convention has a stability level, such as development, release candidate or stable. Stable conventions are not renamed in breaking ways. The HTTP conventions were declared stable in late 2023, which renamed older attributes: http.method became http.request.method, and http.status_code became http.response.status_code. Database conventions followed later, replacing for example db.statement with db.query.text and db.system with db.system.name.

To migrate without breaking dashboards, many instrumentation libraries support the environment variable OTEL_SEMCONV_STABILITY_OPT_IN. With a value such as http/dup they emit both old and new attributes during a transition period; with http they emit only the new ones. The Collector's transform processor can also rename attributes centrally for sources you cannot change quickly.

Best practices

1. Use convention names wherever one exists before inventing your own. Check the specification for your domain first.
2. Namespace custom attributes, for example app.payment.method or acme.tenant.tier, so they never collide with future official names.
3. Always set the core resource attributes: service.name, service.version and deployment.environment.name. They drive service maps, deployment comparisons and filtering.
4. Respect cardinality guidance. Use http.route on metrics, not url.full, to avoid a cardinality explosion.
5. Pin the semconv version your instrumentation emits and plan migrations like any schema change.

Common mistakes

• Mixing old and new attribute names across services, so half the dashboards show gaps.
• Putting user IDs or raw URLs into metric attributes.
• Recording unsanitized SQL with literal values in db.query.text, which can leak personal data.

How Obseria helps

Obseria is OpenTelemetry-native and understands semantic conventions out of the box: service.name, Kubernetes and cloud resource attributes feed Obseria TopoGraph and the service map, and standard HTTP, database and messaging attributes power ready-made views in distributed tracing. Obseria Pipeline can normalize legacy attribute names at ingest, so old and new instrumentation appear consistently. Learn more on OpenTelemetry in Obseria.