RousselTMLEARNING

Article · OpenTelemetry: From Discovery to Expertise

Semantic conventions (semconv)

1. The role of conventions #

A common vocabulary for all telemetry.

The problem #

Before and after conventions
Analysis tools can recognize an HTTP request or an SQL query without configuration.

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 in http.*.

2. Conventions to know #

Resource, HTTP, databases, messaging, GenAI.

Resource #

AttributeExampleNote
service.namecheckoutmandatory
service.version1.4.0link an incident to a version
service.namespaceshopgroup services
service.instance.idprocess uuiddistinguish instances
deployment.environment.nameproductionreplaces deployment.environment
host.name, container.id, k8s.pod.name, k8s.namespace.nameadded by resource detectors and k8sattributes

HTTP (stable) #

AttributeExample
http.request.methodGET
http.route/users/{id}
http.response.status_code503
url.full (client) / url.path (server)https://api/users/42
server.address, server.portapi.example.com, 443
error.type503, 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 #

DomainKey attributesMaturity
Databasesdb.system.name, db.namespace, db.collection.name, db.operation.name, db.query.text (parameters masked)stable for the core attributes
Messagingmessaging.system, messaging.destination.name, messaging.operation.type (send, receive, process)being stabilized
RPC / gRPCrpc.system, rpc.service, rpc.methodin development
GenAIgen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokensin development (see OpenInference)
Exceptionsexception.type, exception.message, exception.stacktracestable

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/dup
Common 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 documentation
Lifecycle of a conventions registry
The versioned registry becomes the teams' common reference.

Checking your data #

Good practice: Add a CI test that starts the application with the console exporter or a test Collector and checks for service.name, service.version and the expected attributes.

📄 OpenTelemetry semantic conventions (semconv): naming telemetry →

My progress

  • ⏱ Estimated time : ≈ 6 min

Sign in to track your progress and take notes. Sign in

💬 Recent discussions about this course

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...

Support us

♥ SUPPORT US

Support RousselTM Learning

Courses, articles, labs and certificates stay free with no intrusive ads. A voluntary contribution, of any amount you choose, pays for hosting, lab environments and new content.

Contribute with PayPal Any amount · card or PayPal accountLearn more
QR code PayPal
Or scan this QR code with your phone

Thank you, every contribution counts!