OpenTelemetry Semantic Conventions

Best Practice: OpenTelemetry Semantic Conventions

OpenTelemetry Semantic Conventions are a shared vocabulary for naming telemetry. They specify standard attribute keys and values (for example http.request.method, db.system, server.address) and how to structure spans, metrics, and logs for common technologies. Without conventions, every team names the same concept differently and dashboards, queries, and alerts cannot be reused.

They matter because consistent attribute names make telemetry portable across backends, comparable across services, and queryable with shared rules. For organizations standardizing observability, conventions are what turn many independent signals into one coherent, analyzable dataset.

The conventions cover many domains: HTTP, database calls, messaging, RPC, cloud and Kubernetes resources, and general resource attributes such as service.name and deployment.environment. They also define stability levels, marking some attributes as stable and others as experimental, so you know which keys are safe to depend on. Because the conventions are versioned, a schema URL travels with the telemetry, letting backends interpret data correctly even as definitions evolve. Following the conventions also means your dashboards, alerts, and queries built on one service work unchanged on the next, which compounds in value as the number of services grows.

Step-by-Step Implementation Guidance

1. Adopt the OpenTelemetry SDK and auto-instrumentation, which emit conventional attributes by default.
2. Pin a stable Semantic Conventions version and record it; conventions evolve and stability levels matter.
3. When adding custom attributes, follow the namespacing rules and reuse registered keys instead of inventing synonyms.
4. Map any legacy or vendor-specific attributes to conventional names at the Collector.
5. Validate emitted telemetry against the conventions in CI where possible.
6. Document any approved custom namespace so teams stay consistent.
7. Track convention version changes and plan migrations when keys are renamed or stabilized.

Common Mistakes Teams Make When Ignoring This Practice

• Inventing per-team attribute names for HTTP, DB, or messaging spans.
• Mixing convention versions across services without tracking them.
• Putting high-cardinality values (user IDs, full URLs) into attributes meant for low cardinality, which inflates storage and slows queries.
• Relying on a single vendor's proprietary schema, creating lock-in.
• Skipping the Collector mapping step for legacy signals.

Tools and Techniques That Support This Practice

• OpenTelemetry SDKs and language auto-instrumentation.
• OpenTelemetry Collector processors for attribute renaming and enrichment.
• The Semantic Conventions registry and semconv schema files.
• Weaver and schema-validation tooling for convention checks.
• Backend support in Grafana, Jaeger, Tempo, and major APM vendors that key off conventional attributes.
• The OpenTelemetry specification's schema URL mechanism for version negotiation.

How This Practice Applies to Different Migration Types

• Cloud Migration: Keep attribute names identical across old and new infra so dashboards survive the move, and rely on standard resource attributes to distinguish environments.
• Database Migration: Use standard db.* attributes to compare query behavior across engines.
• SaaS Migration: Normalize third-party signals to conventions at the Collector for unified views.
• Codebase Migration: Conventional instrumentation lets traces span both old and rewritten components coherently.

Checklist

• OpenTelemetry SDK and auto-instrumentation adopted
• Semantic Conventions version pinned and recorded
• Custom attributes follow namespacing rules
• Legacy attributes mapped at the Collector
• Telemetry validated against conventions
• Approved custom namespaces documented
• Convention version changes tracked