OpenTelemetry Semantic Conventions: Standard Attributes & Names

Q: How do I handle the HTTP convention rename?

Upgrade instrumentation libraries and set OTEL_SEMCONV_STABILITY_OPT_IN=http/dup to emit old and new names together. Update dashboards and alerts to the new names, then switch the opt-in to http (new only). The Collector's transform processor can also rename attributes centrally.

OpenTelemetry Semantic Conventions

Telemetry is only useful if everyone describes the same things the same way. If one service records the HTTP method as method, another as http_method, and a third as verb, no dashboard, alert, or query works across all three. Semantic conventions are OpenTelemetry's shared vocabulary: standard attribute names, values, units, span names, and metric names for common concepts like HTTP requests, database calls, messaging, cloud resources, and generative AI.

Following them means instrumentation libraries, the Collector, and observability backends all understand your data out of the box. Backends can build service maps, RED dashboards, and database query views automatically, and your custom attributes slot in consistently alongside them.

TL;DR

Semantic conventions define standard names for resource, span, metric, log/event, and exception attributes.
Resource conventions identify the source: service.name, service.version, deployment.environment.name, k8s.*, cloud.*, host.*.
Domain conventions cover HTTP (http.request.method, http.response.status_code, url.path, http.route), databases (db.system.name, db.query.text), messaging, RPC, FaaS, and GenAI (gen_ai.*).
Standard metric names exist too, for example http.server.request.duration (histogram, seconds).
Conventions have stability levels; HTTP became stable, and the OTEL_SEMCONV_STABILITY_OPT_IN setting eases migration.
Name custom attributes with a namespace prefix (app., acme.), in lowercase dotted snake_case.

Quick Example

An HTTP server span following current conventions:

And a database client span:

Core Concepts

Resource Attributes

Resources describe what produced the telemetry and apply to all spans, metrics, and logs from a process:

Resource detectors and the Collector's k8sattributes and resourcedetection processors fill most of these automatically.

Span Conventions by Domain

HTTP: http.request.method, http.route, http.response.status_code, url.full (client), url.path and url.query (server), server.address, server.port. Span names are {method} {route}.
Database: db.system.name, db.namespace, db.operation.name, db.collection.name, db.query.text (sanitized), db.response.status_code.
Messaging: messaging.system (kafka, rabbitmq, aws_sqs), messaging.destination.name, messaging.operation.type (send, receive, process), messaging.message.id, messaging.kafka.*, and similar. Producer and consumer span kinds.
RPC: rpc.system (grpc), rpc.service, rpc.method, rpc.grpc.status_code.
Exceptions: exception.type, exception.message, exception.stacktrace on exception events.
GenAI: gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, and operation names for chat, embeddings, and tool calls. Used for LLM observability. See LLMOps.

Metric Conventions

Standard instrument names, types, and units make metrics portable:

Metric attributes are a low-cardinality subset of span attributes: http.route rather than url.path. When exported to Prometheus, dots become underscores and units become suffixes (http_server_request_duration_seconds).

Stability and Migration

Each convention has a status: development (experimental), release candidate, or stable. HTTP conventions stabilized with breaking renames (for example http.method → http.request.method, http.status_code → http.response.status_code, net.peer.name → server.address). Instrumentation libraries support the environment variable OTEL_SEMCONV_STABILITY_OPT_IN=http/dup to emit both old and new names during a migration window, so you can update dashboards before switching to new names only. Database and messaging conventions have gone through similar transitions.

Custom Attributes

For business and application-specific data, follow the same style:

Namespace your attributes: app.order.id, acme.tenant.tier, checkout.cart.items, to avoid collisions with current and future standard names.
Use lowercase, dot-separated namespaces with snake_case components (app.payment.provider_name).
Reuse standard attributes where they fit: user.id, enduser.*, and error.type exist before you invent your own.
Document your custom conventions, and consider OpenTelemetry Weaver to define them as a registry, generate code constants, and validate emitted telemetry in CI.

Best Practices

Let Instrumentation Libraries Set Standard Attributes

Auto-instrumentation already emits conventions for HTTP, databases, and messaging. Don't duplicate them with custom names. Add only what's missing, like business context.

Sanitize Sensitive Values

Conventions like db.query.text and url.full can capture secrets or PII. Use parameterized queries, strip query strings and credentials, and apply redaction in the Collector. See PII handling.

Keep Cardinality Appropriate per Signal

High-cardinality attributes (url.path, user IDs) are fine on spans and logs but not on metrics. Follow the metric conventions' attribute lists, which are chosen to stay bounded.

Plan Convention Upgrades

Track instrumentation library versions and release notes, use dual-emit opt-ins during migrations, and update queries, dashboards, and alerts before dropping old names.

Common Mistakes

Inventing Names for Standard Concepts

Un-Namespaced Custom Attributes

Attributes like tier or order_id risk colliding with future standard names and are ambiguous across teams. Prefix them (app.customer.tier).

Mixing Old and New Convention Versions Silently

Services on different instrumentation versions emitting http.status_code and http.response.status_code break cross-service dashboards. Standardize versions, or use Collector transforms to normalize during migrations.

FAQ

Why do semantic conventions matter if I can name attributes anything?

Because tooling depends on them. Backends generate service maps, RED metrics, error views, and database dashboards by recognizing standard attributes. Consistent names also let one query work across all services and languages, and make telemetry portable between vendors.

What's the difference between resource attributes and span attributes?

Resource attributes describe the entity emitting telemetry (service, host, pod, cloud region) and are shared by everything that process emits. Span attributes describe a specific operation (this request's route, status code, and query). Put identity on the resource, and per-operation details on spans.

How do I handle the HTTP convention rename?

Upgrade instrumentation libraries and set OTEL_SEMCONV_STABILITY_OPT_IN=http/dup to emit old and new names together. Update dashboards and alerts to the new names, then switch the opt-in to http (new only). The Collector's transform processor can also rename attributes centrally.

Are there conventions for LLM and GenAI telemetry?

Yes. The GenAI semantic conventions define attributes and metrics for model calls (provider, model, token usage, finish reasons), embeddings, and agent or tool operations, plus events for prompts and completions (opt-in because of sensitivity). They're adopted by many LLM observability tools. See LLMOps.