1. The role of conventions #
A common vocabulary for all telemetry.
The problem #
Semantic conventions (« semconv ») define the names, types, units and allowed values of attributes, spans, metrics and events. They let a backend automatically display a service map, detect a slow SQL query or compute an HTTP error rate, whatever the language or library.
Naming rules #
- Lowercase namespaces separated by dots:
http.request.method,db.collection.name. - Words separated by
_within a segment:http.response.status_code. - Explicit UCUM units in the metric (
s,By,{request}), never in the name. - Attributes specific to your domain in your own namespace:
shop.cart.items, never inhttp.*.
2. Conventions to know #
Resource, HTTP, databases, messaging, GenAI.
Resource #
| Attribute | Example | Note |
|---|---|---|
service.name | checkout | mandatory |
service.version | 1.4.0 | link an incident to a version |
service.namespace | shop | group services |
service.instance.id | process uuid | distinguish instances |
deployment.environment.name | production | replaces deployment.environment |
host.name, container.id, k8s.pod.name, k8s.namespace.name | added by resource detectors and k8sattributes |
HTTP (stable) #
| Attribute | Example |
|---|---|
http.request.method | GET |
http.route | /users/{id} |
http.response.status_code | 503 |
url.full (client) / url.path (server) | https://api/users/42 |
server.address, server.port | api.example.com, 443 |
error.type | 503, timeout, java.net.UnknownHostException |
Span name: {method} {route}, for example GET /users/{id}, never the full URL (cardinality). Metrics: http.server.request.duration and http.client.request.duration, histograms in seconds.
Databases, messaging, GenAI #
| Domain | Key attributes | Maturity |
|---|---|---|
| Databases | db.system.name, db.namespace, db.collection.name, db.operation.name, db.query.text (parameters masked) | stable for the core attributes |
| Messaging | messaging.system, messaging.destination.name, messaging.operation.type (send, receive, process) | being stabilized |
| RPC / gRPC | rpc.system, rpc.service, rpc.method | in development |
| GenAI | gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens | in development (see OpenInference) |
| Exceptions | exception.type, exception.message, exception.stacktrace | stable |
3. Stability and migration #
Conventions evolve: be prepared.
Versions and schema URL #
Conventions are versioned (v1.26, v1.30…). Each instrumentation declares the version it follows through a schema URL (https://opentelemetry.io/schemas/1.26.0). When the HTTP conventions were stabilized, many attributes were renamed (http.method → http.request.method, http.status_code → http.response.status_code).
# Pendant une migration : émettre les anciens ET les nouveaux attributs
export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup # puis "http" quand les tableaux de bord sont migrés
export OTEL_SEMCONV_STABILITY_OPT_IN=database/dupCommon mistake: An instrumentation upgrade can rename attributes and break dashboards or alerts. Read the release notes and use the dup mode during the transition.Normalizing in the Collector #
processors:
transform/semconv:
trace_statements:
- context: span
statements:
- set(attributes["http.response.status_code"], attributes["http.status_code"]) where attributes["http.status_code"] != nil
- delete_key(attributes, "http.status_code")4. Your own conventions #
Extending without diverging.
In-house conventions #
- First reuse a standard attribute if one exists.
- Create a namespace specific to the company or the domain (
shop.,acme.). - Document each attribute (type, unit, examples, expected cardinality) in a versioned registry.
- Forbid high-cardinality attributes on metrics (user identifiers, full URLs).
OTel Weaver is the project's tool for describing a conventions registry in YAML, validating it, generating documentation and code constants, and checking that the telemetry actually emitted complies with the registry.
weaver registry check -r ./mon-registre # valider le registre
weaver registry generate -r ./mon-registre markdown docs/ # générer la documentationChecking your data #
Good practice: Add a CI test that starts the application with the console exporter or a test Collector and checks forservice.name,service.versionand the expected attributes.
My progress
Sign in to track your progress and take notes. Sign in
💬 Recent discussions about this course
- Quels attributs utiliser pour nommer mes spans HTTP (semconv) ?✓ solved · 1 reply(ies)
- OpenTelemetry Collector : mes traces arrivent mais pas mes métriques✓ solved · 2 reply(ies)
Ask a question about this lesson →See all discussions about this course
Recommended Articles
OpenInference: the OpenTelemetry conventions for tracing AI applications
Detailed guide to OpenInference: OpenTelemetry semantic conventions and instrumentations for LLMs...
OpenTelemetry (OTel) best practices: the guide to modern observability
Master OpenTelemetry with our expert advice: implementing the Collector, following semantic conve...
OpenTelemetry: automatic vs manual instrumentation
Understand the differences between automatic and manual instrumentation with OpenTelemetry, their...
Core OpenTelemetry concepts: signals, resources, context and maturity
The essential OpenTelemetry vocabulary: the four signals, API and SDK, resource and instrumentati...
OpenTelemetry traces in depth: spans, status, events, links and sampling
Master the trace signal: anatomy of a distributed trace, span and SpanKind, attributes, status an...
Grafana Alloy environment variables: GOMEMLIMIT, sys.env and OTEL_RESOURCE_ATTRIBUTES
Which variables does Grafana Alloy actually read? GOMEMLIMIT, HTTP_PROXY, sys.env, OTEL_RESOURCE_...
OTLP explained: understanding the OpenTelemetry protocol
The OTLP protocol explained simply. Understand the differences between gRPC and HTTP for exportin...
OpenTelemetry Collector: processors (transforming, filtering and protecting telemetry)
Master OpenTelemetry Collector processors: batch, memory_limiter, attributes, resource, filter, t...
Correlating traces, metrics, logs and profiles with OpenTelemetry
Link the four signals to diagnose quickly: shared resource, trace_id in logs, exemplars on metric...