OpenTelemetry semantic conventions give telemetry a shared meaning: names, attributes, units, span kinds, resource identity, and allowed values that producers and consumers can interpret consistently. Governance is needed because the conventions cover many domains, versions evolve, and their stability differs. A platform team that simply publishes a long attribute list will create local dialects. A better system owns decisions, tracks upstream maturity, tests emitted data, and migrates producers and queries together.
As of July 13, 2026, the official OpenTelemetry semantic conventions are version 1.43.0. The registry spans applications, cloud resources, databases, messaging, CI/CD, runtime, and more. That breadth is useful precisely because teams should not invent service, http, or database meanings independently. It also means governance must be version-specific: saying “we follow OpenTelemetry” is not a testable contract.
Scope a semantic-convention governance contract
Define the governed surface first. Include resource attributes required for identity, approved instrumentation libraries and versions, span and metric naming, mandatory and conditional attributes, units, cardinality constraints, privacy classes, and the backend transformations that preserve or change meaning. Name an observability schema owner, domain maintainers, and application owners. The central team curates and tests the contract; domain experts decide whether database, messaging, or product-specific semantics are correct.
Pin an upstream semantic-convention version in the contract. Record each adopted group’s stability and any local restriction. The semantic convention groups identify development, alpha, beta, release-candidate, and stable states and support deprecation metadata. Stable does not mean every backend query automatically survives a producer upgrade; it means the upstream compatibility expectations are stronger. Experimental adoption still needs an owner, consumer inventory, and exit path.
| Layer | Default authority | Local decision | Evidence |
|---|---|---|---|
| Resource identity | OpenTelemetry plus platform catalog | required service, environment and deployment mapping | sample resources and ownership resolution |
| Protocol semantics | upstream domain convention | adopted group and version | golden traces and spans |
| Metric contract | upstream instrument and unit | aggregation, temporality and approved dimensions | scrape or OTLP fixture with query test |
| Custom business data | domain owner under central policy | namespace, definition and privacy class | consumer and retention record |
| Backend representation | observability platform | translation and compatibility window | old and new query comparison |
Design a narrow custom-attribute policy
Prefer an upstream attribute when its definition matches. Do not reuse a standard name with a different type, unit, or meaning. A custom attribute needs a documented namespace, owner, type, allowed values, cardinality expectation, privacy classification, producing systems, consuming queries, and review date. Business dimensions such as plan or workflow may be legitimate, but raw email addresses, unrestricted URLs, SQL text, session identifiers, and customer-provided strings can create privacy and cost hazards.
Control cardinality at the point where the attribute becomes a metric dimension, not by deleting useful trace context indiscriminately. A request identifier can be appropriate on a sampled trace and disastrous as a metric label. Specify signal-specific use. Normalize bounded values, strip query strings where paths are intended, and keep tenant identifiers behind explicit access and retention controls. Automated checks should fail type conflicts and forbidden sensitive fields, while cardinality observations catch real-world value growth.
Build semantic conformance tests from fixtures
Create representative fixtures for inbound HTTP, outbound HTTP, database calls, messaging publish and consume, background jobs, errors, and asynchronous links. Capture emitted resources, spans, events, metrics, and exemplars. Tests should verify required attributes, types, span names, status behavior, units, parentage, prohibited fields, and bounded dimensions. Keep expected data semantic rather than byte-for-byte where timestamps and generated identifiers vary. Run the suite against every approved language distribution and collector release.
Add consumer tests. Execute alert rules, service maps, SLO queries, dashboards, retention routing, sampling rules, and access controls against old and candidate telemetry. Producer conformance alone cannot detect a backend that renames an attribute or a query that depends on deprecated behavior. Sample production traffic in a shadow pipeline and report unknown values and missing identity. Conformance is the combination of correct emission, preserved transport, and correct interpretation.
| Change | Risk | Migration method | Release gate |
|---|---|---|---|
| Add optional attribute | cost and privacy growth | canary then bounded adoption | cardinality and access review |
| Rename or deprecate attribute | query and correlation breakage | dual emit or translate for a window | consumer inventory reaches zero old reads |
| Change type or unit | silent numerical error | new field plus explicit conversion | old/new result reconciliation |
| Change span name | service map and latency aggregation shift | shadow production and rewrite queries | topology and alert parity |
| Adopt unstable group | future churn | time-boxed exception with owner | documented rollback and upgrade test |
Migrate producer and consumer schemas together
OpenTelemetry schemas provide a mechanism for describing transformations between telemetry schema versions, but schema URLs are not magic compatibility. Inventory SDKs, auto-instrumentation, collector processors, agents, gateways, exporters, and backend parsers. Choose whether compatibility is achieved at producers, a collector translation boundary, ingestion, or queries. Keep one authoritative transform location where possible so teams do not stack conflicting rewrites.
Roll out by service cohort and compare semantic results, not only ingest success. Measure missing required attributes, deprecated usage, unknown custom fields, series count, span volume, error classification, service graph edges, and alert differences. Dual emission can ease a rename but temporarily increases payload and cardinality; bound its duration. A migration closes only when producers have moved, consumers no longer read the old form, transforms are removed, and historical query behavior is documented.
Operate a registry with exceptions and expiry
Publish a machine-readable profile that references the upstream version and adds local requirements. Generate human documentation from the same source. Each exception should state business need, affected signal, owner, privacy assessment, consumers, and expiry. Review upstream release notes on a regular cadence, but do not force fleet-wide upgrades merely because a new version exists. Prioritize security fixes, adopted-group changes, and changes that unlock an identified consumer outcome.
Measure governance by conformance coverage, unknown attribute age, deprecated usage, exception expiry, identity resolution, migration duration, and consumer regressions. Counting documented fields rewards paperwork. The objective is interoperable data that remains understandable through upgrades. Give teams a reference distribution and testing library so the approved path is easy, while keeping the contract small enough that a service owner can explain what each required field means.
Design release channels for the local telemetry profile. A stable channel should include only organization-approved stable or deliberately frozen conventions and receive compatibility fixes on a predictable cadence. An evaluation channel can expose newer upstream groups to volunteer services and non-paging consumers. Record the profile version as deployment metadata or a resource attribute where appropriate, so a failed query can be traced to the emitting contract. Do not let teams opt into individual fields from a migration halfway through; coherent profiles are easier to test, support, and retire than arbitrary mixtures.
Handle disagreement through examples rather than naming preference. When two teams interpret an operation differently, capture representative spans, the upstream definition, desired queries, and privacy or cardinality effects. The domain maintainer decides meaning, while the platform owner decides whether the data can be transported and operated safely. Record rejected alternatives because the same debate often returns during a library upgrade. This decision log also prevents a backend dashboard label from becoming the de facto schema without review. Governance should make correct semantics faster to adopt, not turn every attribute into a committee meeting.
Include generated and vendor instrumentation in the same controls. Auto-instrumentation can change emitted names or attributes when a distribution upgrades even though application code did not change. Maintain an approved compatibility matrix across language agents, framework versions, and the local profile; canary upgrades with captured fixtures; and make unexpected semantic output visible in deployment checks. Where a vendor enriches telemetry after ingestion, document that field as backend-derived rather than upstream-conformant. This distinction matters during migration and prevents teams from depending unknowingly on data that another OpenTelemetry backend will not produce.
Key takeaways
- Pin the exact upstream semantic-convention version and stability of every adopted group.
- Govern resource identity, signal semantics, privacy, cardinality, and backend transforms as one contract.
- Use standard attributes only when their type and meaning match; namespace and review custom data.
- Test producers, collectors, backends, and queries with representative fixtures and shadow traffic.
- Close migrations by removing old consumers and temporary transforms, not merely upgrading SDKs.
Frequently asked questions
Are custom attributes forbidden?
No. They are appropriate when no standard meaning fits, but they need a namespace, owner, type, privacy and cardinality controls, consumers, and a review date.
Does stable mean a convention never changes?
Stable carries stronger compatibility expectations, but producer, collector, and backend upgrades still require consumer tests. Local transformations can break semantics even when upstream is stable.
Where should schema translation happen?
Choose one controlled boundary that can observe and test both forms, often a collector gateway or ingestion layer. Avoid overlapping rewrites across applications and multiple collector tiers.
Conclusion
Semantic conventions become an interoperability asset only when adoption is precise. Pin versions, delegate domain meaning, constrain custom data, and test the whole producer-to-query path. With staged migrations and expiring exceptions, teams can gain shared telemetry language without turning every upstream change into a fleet-wide surprise.