Telemetry is only useful when different people can read it the same way. Names are the first thing that drifts.

What Telemetry Looks Like Up Close

Telemetry is the stream of data a running system produces about itself. It comes in three kinds, called signals: traces, which follow one request through many services; metrics, which are numbers measured over time; and logs, which are timestamped text records. Each piece of telemetry carries attributes, which are named labels such as the name of the service, the HTTP method used, or the region where the code ran.

Every attribute has a key (its name) and a value. Dashboards, alerts and queries are written against keys. A query like “show me the slowest requests where the method is POST” only works if every system uses the same key for the method, and spells the value the same way.

How Drift Happens

Nobody plans for naming to go wrong. It happens one reasonable decision at a time. A developer copies an example from a blog post. A library author chooses the name that felt natural in their language. A vendor agent uses its own names. A team inherits a service from an acquisition. After a few years, the same fact is stored under five different keys.

The Hidden Cost

Inconsistent naming does not break systems loudly. It quietly raises the cost of everything built on top of telemetry.

• Dashboards multiply. Each team builds its own because the shared one does not fit their names.
• Alerts go silent. A rule written for one key never fires for services that use another.
• Cost reports lie. Spend is grouped by an attribute that only half the services set.
• Security rules leak. A redaction rule that hides one key misses its twin spelled differently.
• Migrations stall. No one knows which services use which names, so nobody dares rename anything.

Before a label can say which edition of the dictionary you used, you need to know what the dictionary contains.

What They Are

Semantic conventions, often shortened to semconv, are the agreed names, types, units and meanings for common pieces of telemetry. They answer questions such as: what is the exact key for the HTTP method, what type of value does it hold, which values are allowed, and is it required or optional? They also define names for metrics, such as the standard name for the duration of a server request, together with the unit it must use.

Conventions cover many areas: HTTP and RPC calls, databases, messaging systems, cloud providers, containers and Kubernetes, operating system processes, and more. They are grouped into families by a dotted prefix, for example everything about the user’s browser starts with browser. and everything about the destination server starts with server..

The Pieces of One Convention

Where They Live and How They Were Born

Semantic conventions are maintained in an open repository, with a published registry of every attribute and a human-readable website. Earlier they lived inside the main specification. They were split out so they could evolve on their own schedule, with their own releases.

Their roots run deep. Before OpenTelemetry, the OpenTracing project suggested standard tag names, while OpenCensus had its own habits. When the two projects merged in 2019, aligning names became a priority. In 2023 Elastic contributed its Elastic Common Schema, a mature naming scheme used by many log and security tools, and the two efforts were merged under OpenTelemetry. That history explains why the conventions are broad: they are an attempt to settle naming across tracing, metrics, logs and security data in one vocabulary.

Stability Levels

Not every convention is equally settled, and the project is honest about it. Each attribute and group is marked with a stability level. Roughly speaking, development means the name may still change, stable means it is safe to build on and will not be broken without a long, managed process, and deprecated means it is being phased out in favor of a replacement. A release candidate level sometimes sits between development and stable for bigger families. Knowing the level is the first governance tool: you may decide your organization uses only stable conventions in alerts, while allowing development ones in experiments.

A dictionary changes between editions. The schema URL is the edition number printed on the cover of your data.

What a Schema URL Is

A schema URL is a web address that identifies a specific version of a set of naming rules. For OpenTelemetry’s own conventions, such an address looks like the standard site followed by a path ending in a version number, for example the address of release 1.21.0 of the conventions. It travels along with the telemetry, so anyone who receives the data can see which edition its names come from.

The address has a simple shape. Everything before the final slash is the schema family, which names the whole line of schemas. The last piece is the version, written in the familiar three-number style: major, minor and patch. Two addresses in the same family differ only in that last piece. This is what allows tools to compare them and decide which is newer.

Where the Label Is Attached

Telemetry in OTLP, the OpenTelemetry Protocol that moves data between components, is organized in layers. At the top is a resource: a description of the thing that produced the data, such as a service, container or host. Below that sits a scope: the instrumentation library, a piece of code that created the spans, metrics or log records. Inside the scope are the data points themselves.

A schema URL can be attached at two of these layers. The one on the resource says which edition governs the resource’s attributes, such as service.name. The one on the scope says which edition governs the attribute names used by that library’s data. Because they are separate, a single payload can honestly say: “my resource follows edition 1.26.0, but this older library follows 1.21.0.”

flowchart TD
  R["Resource
who produced the data
carries a schema URL for resource attributes"] --> S["Scope
which library produced it
carries its own schema URL"]
  S --> D["Spans, metric points or log records
attribute names follow the scope's edition"]
    

An Identifier, Not a Download

The address is meant to be dereferenceable, which means you can open it and get a file describing the edition. But in normal operation SDKs and Collectors do not fetch it while handling each piece of data. Most treat it as an identifier, the way a library treats a version string. Only tools that actually translate data between editions, covered later, need to read the file behind the address.

Another important property is immutability. Once an edition is published at an address, its contents must never change. If the file behind version 1.21.0 could be edited, the label would stop meaning anything. A fix always becomes a new version, never an edit of an old one.

The address points to a file. That file is a short history of what changed between editions, written so that a program can apply it.

What the File Contains

A schema file is a small structured document. It declares the version of the file format itself, repeats its own address, and then lists editions, usually newest first. For each edition it records the changes made in that release, grouped by what they affect: resource attributes, spans, span events, metrics, logs, or everything at once.

The most common kind of change is a rename: “the attribute called A is now called B”. Other recorded changes include renaming a metric or renaming an event. The point is not to describe the whole dictionary. The point is to describe only the movements between editions, so that a program can walk from one edition to another.

Walking Forward and Backward

Because the file records each edition’s renames, a tool can convert data in either direction. To move data forward from edition 1.20.0 to 1.22.0, it applies the renames of each edition in between, in order. To move backward, it applies the same renames in reverse, swapping the old and new names. This is why renames are the ideal kind of change for a schema file: they can be undone exactly.

flowchart LR
  A["Data labelled
edition 1.21.0"] --> B["Schema processor"]
  F["Schema file
renames per edition"] --> B
  B --> C["Data rewritten with
edition 1.26.0 names"]
  C --> D["Backend and dashboards
one consistent naming"]
    

What a Schema File Cannot Do

This is a critical limit. A schema file records renames. It does not convert values. It cannot turn milliseconds into seconds, change a number into a string, merge two attributes into one with new logic, or fix a change in meaning. When a metric moved from reporting milliseconds to seconds, the new metric got a new name as well as a new unit. A tool can rename between them, but it cannot divide the values by one thousand on its own.

That is why the conventions project treats breaking changes with great care. Any change that goes beyond a rename needs a separate plan: extra emitted data, documented opt-in switches, or consumer-side adjustments.

Examples of Real Renames

Concepts become real when you can look at a batch of telemetry and say what each part tells you. Here is a guided tour in words.

A Batch Seen From the Outside

Picture a batch of traces sent by one checkout service. At the very top is a single resource entry. It lists the service name, the version of the release, the environment, the cloud region and the pod. Directly beside those attributes sits the resource’s schema URL, naming the edition of the conventions those attributes follow.

Beneath the resource are several scope entries, one for each instrumentation library that produced spans in this batch. One scope belongs to the web framework library. Another belongs to the database driver library. A third belongs to the team’s own hand-written instrumentation. Each scope has a name and a version of that library, and each may carry its own schema URL. Inside each scope sit the spans, and each span carries attributes.

Three Questions to Ask of Any Payload

What You Can Do With This View

Once you can read a payload this way, several governance jobs become easy. You can count the scopes by edition across the whole fleet and see which libraries lag behind. You can find which team’s code produces unlabelled scopes. You can check that a pipeline step did not drop the labels, and you can identify exactly which library introduced a surprising name after an upgrade, because every scope carries its own name and version next to its own edition.

This is the practical payoff of putting labels at two layers. A single label for the whole payload would be forced to either hide the mix or lie about it. Two layers tell the truth, and the truth is what makes cleanup possible.

The dictionary of names is never finished. Versioning is the set of rules that lets it grow without surprising the people who depend on it.

Releases and Version Numbers

The semantic conventions are published as numbered releases in the familiar three-part style, such as 1.21.0 or 1.26.0. New releases appear frequently, often every month or two. Each release comes with a change log listing added, renamed and deprecated entries, and each corresponds to a schema URL and a schema file that records the renames. The release number is therefore the same thing as the edition number in the schema URL.

Four Different Version Numbers

A frequent source of confusion is that several unrelated version numbers exist in any telemetry setup. They move independently, and mixing them up leads to wrong conclusions.

Only the last one is what a schema URL records. Upgrading an SDK from one release to the next does not by itself say anything about which naming edition it now uses. That has to be read from the package notes or from the schema URL on the data itself.

What Counts as a Breaking Change

For governance, the key question is what a consumer of telemetry would notice. A change is breaking if a dashboard, alert, query or rule written against the old edition would give a different or empty answer after the change. That includes more than renames.

• Renaming an attribute or metric, because old queries no longer find it.
• Removing an attribute that was previously present.
• Changing a unit, such as milliseconds to seconds, because values shift by a factor.
• Changing a type, such as a number to a string, because comparisons stop working.
• Changing meaning, such as which address the attribute describes, because values look the same but mean something else.
• Changing how values are grouped, such as splitting one attribute into two, which changes cardinality and the shape of every chart.

The Life of One Convention

Labels only help if the code that produces telemetry sets them honestly. Here is where that happens.

Setting the Label in the SDK

The SDK is the library inside your application that collects and prepares telemetry. It builds a resource describing the application and obtains tracers, meters and loggers, the handles through which instrumentation creates spans, metrics and logs. When code asks for a tracer, it supplies a name, optionally a version, and optionally a schema URL. That schema URL becomes the label on the scope in the exported data.

The resource can carry its own schema URL as well. Resource attributes such as the service name and the deployment environment are governed by the edition the SDK or resource detector was written against, so SDKs that attach a schema URL to the resource are saying which edition those names come from.

When Two Labels Meet

Resources can be merged, for example when a base resource from the SDK is combined with extra details from environment variables or detectors. If both sides carry different schema URLs, the merge has a conflict, because the result cannot honestly claim a single edition. The specification treats this as an error case, and implementations decide how to react. Many simply keep the label of one side or drop it, which is a reminder that labels are only as good as the care taken when they are set.

Versioned Convention Packages

Each language ships a package of constants for convention names, so that developers do not type strings by hand. These packages are versioned by convention edition, and the ecosystem has settled into a few helpful patterns.

• Go publishes a separate package path for each edition, so choosing an import path is choosing an edition. Upgrading is a visible, deliberate edit.
• JavaScript offers a main entry point containing stable names and a separate “incubating” entry point for development-level ones.
• Java splits stable and incubating names into separate artifacts for the same reason.

The split between stable and incubating matters for governance. A policy such as “production code may import only the stable package” is easy to enforce in a code review or a build check, and it prevents accidental dependence on names that may still move.

Instrumentation Libraries Pick Their Own Edition

Instrumentation libraries wrap popular frameworks and clients, such as web servers and database drivers, and create telemetry automatically. Each library is written against some edition of the conventions and should label its scope accordingly. Because they are released and upgraded at different times, a single application often mixes editions. The web framework library may follow a recent edition while an older queue library follows one from a year before. Scope-level schema URLs make this honest: each part of the payload names its own edition.

Auto-Instrumentation Agents Change Names Silently

Many teams attach an agent to their application that instruments dozens of libraries without code changes. Upgrading that agent upgrades every library inside it at once, and the naming edition can jump with it. No application code changed and no engineer touched a dashboard, yet attributes may have been renamed overnight.

Once data leaves the application, the Collector and the backend decide whether the label is respected, translated or ignored.

The Collector in the Middle

The OpenTelemetry Collector is a separate program that receives telemetry, processes it and forwards it. It is built from receivers that accept data, processors that change or filter it, and exporters that send it onward. It carries schema URLs through unchanged by default, so labels set by the SDK arrive at the backend intact.

Because it sits between all applications and the backend, the Collector is the natural place for governance that applies to everybody. Among its optional components is an experimental schema processor that reads the schema URL on incoming data, finds the schema file, and rewrites names to a target edition you choose. It is the practical expression of the idea in Figure 2. Its maturity has been limited, so check its current status and test it with your own traffic before relying on it.

Labels Must Tell the Truth

If you change names inside the Collector using general-purpose processors, such as one that renames or copies attributes, remember that the label still says the old edition. A payload whose label says edition 1.21.0 but whose content mixes new names is lying. Later tools may apply renames that have already been applied, or skip renames that are still needed. Whenever a pipeline rewrites names, it should also update the schema URL to the edition the data now matches, or remove the label entirely, rather than leave a false one.

What Backends Do

Backends vary. Some store the schema URL as a plain field and let you filter by it, which is very useful for tracking adoption. Some ignore it. Some perform their own normalization when data arrives, using rules that are proprietary and may not follow the schema files. As far as is publicly known, fully automatic cross-edition translation inside backends is uncommon, so most organizations still decide for themselves where normalization will happen.

Three Places to Normalize

Most mature organizations combine them: Collector-level normalization as a safety net, source-level upgrades as the long-term fix, and query-level tolerance only for short transition windows.

The biggest example of convention versioning so far is the HTTP family. Studying it shows what a managed breaking change looks like in practice.

Why the Change Happened

The first HTTP conventions grew organically and carried inconsistencies. Some names mixed client and server perspectives, some attributes bundled several facts into one, and some metrics used milliseconds while the wider ecosystem favored seconds. During the stabilization work that finished with release 1.23.0, the project redesigned the family so that it could be declared stable and then left alone. That meant many names changed once, in a planned way.

Some of the Changes

The mappings above are simplified. The release notes contain the precise rules, including edge cases. What matters here is the variety: some changes are pure renames, some are splits, and one changes the unit. Only the first group can be handled by a schema file alone.

The Opt-In Switch and Dual Emission

The project did not expect millions of dashboards to change on one day. Instrumentation libraries that existed before the redesign were asked to keep emitting the old names unless told otherwise, and to offer an environment variable that controls the transition. Its name is OTEL_SEMCONV_STABILITY_OPT_IN. With no value, the library keeps its older behaviour. With the value http, it emits only the new names. With the value http/dup, it emits both old and new names together. Other families that stabilize later use similar values.

The Four Phases

flowchart LR
  P1["Phase 1
Old names only"] --> P2["Phase 2
Emit old and new together"]
  P2 --> P3["Phase 3
Move dashboards and alerts"]
  P3 --> P4["Phase 4
New names only"]
    

In phase two, producers upgrade and send both sets of names. Nothing breaks because the old names are still there. In phase three, owners of dashboards, alerts and queries move them to the new names and verify the results. Only when every consumer has moved does phase four turn off the old names.

The Price of Overlap

Dual emission is not free. Every span carries extra attributes, and every metric exists twice under two names. A service that produced 2,000 HTTP metric series before may produce about 4,000 during the overlap, which affects network traffic, backend storage and cost. This is a strong reason to keep the overlap window short and planned, and to measure how many consumers are still using old names so that you can end the overlap on time.

Before any span or metric is useful, someone must know which service produced it. Resource attributes carry that identity, and everything else depends on them.

What the Resource Says

A resource describes the entity that produces telemetry: a service, a container, a host, a function. Its attributes are attached once and apply to everything that entity emits, so they are the cheapest and most powerful place to enforce consistency. Typical resource attributes name the service, its namespace and version, the deployment environment, the cloud provider and region, and, in Kubernetes, the namespace and pod.

The One Attribute That Must Always Be Set

The service name is the anchor for nearly every dashboard and alert. When an SDK is not given one, it falls back to a placeholder that starts with the words “unknown service” followed by the name of the running program. A fleet full of such placeholders produces telemetry that cannot be attributed to an owner. Many governance programs begin with one simple rule: no service goes to production without a real service name, enforced by a check in the deployment pipeline and a Collector rule that flags the placeholder.

A Baseline for Every Service

Detectors and Their Editions

Many resource attributes are not typed by developers but discovered by resource detectors, small pieces of code that inspect the environment and report what they find. Detectors are libraries with their own versions, and each follows some edition of the conventions. Two detectors in the same process may disagree about names. A governance program should list the detectors it allows, know the edition each one follows, and test the combined resource in a live check.

Why the Resource Label Matters Most

The schema URL on the resource tells every downstream tool which edition governs these identity attributes. When a rename such as the environment attribute moves to a new key, the resource label is what lets a Collector decide whether the incoming data still needs translating. Because resources are shared by every item a service emits, a mistake here spreads everywhere. Treat the resource layer as the most carefully governed part of the pipeline.

Conventions cover more than attribute keys. The names of spans, the shape of error information and the structure of log records are governed too.

Span Names Should Stay Few

A span name is the short title of one step in a trace. Backends group spans by name to draw summaries, so names must come from a small, bounded set. The conventions recommend names built from the method and the route template, in the style “GET /users/{id}”, not from the actual path with a real identifier in it. If every user identifier produced its own span name, the backend would face millions of unique names, and summary views would become useless and expensive.

Error Information Has a Shape

When something fails, tools need to find the cause quickly. The conventions provide a standard attribute for the type of error and a standard shape for exceptions, with fields for the exception type, message and stack trace. If every team invents its own error attribute, a cross-service error dashboard needs one query per team. With the standard shape, one query covers the fleet, and tools can offer built-in views for errors without custom setup.

Stack traces and messages may contain sensitive data, such as values from user input. Governance should decide whether these fields are kept, truncated or removed in each environment, and apply that decision consistently through redaction rules that use the standard names.

Logs and Events

A log record has a timestamp, a severity, a body and attributes. Conventions describe how logs correlate with traces through identifiers for the trace and span, so that a log line can be shown inside the trace that produced it. They also describe events, which are log records that represent something meaningful that happened, such as a user signing in. Recent versions treat the event name as a first-class part of the record, so that dashboards can count events by name without parsing text.

• Prefer attributes to text. A fact in an attribute can be filtered and counted; the same fact inside a sentence cannot.
• Keep the body readable. Humans still read logs, so the body should say what happened in a clear sentence.
• Always carry trace identifiers. Without them, logs cannot join traces.
• Standardize severity. Agree how your teams use levels like warning and error so alerts mean the same thing everywhere.

Span Kinds and Why They Matter

Each span has a kind that says whether it represents a server handling a request, a client making one, a producer sending a message, a consumer receiving it, or internal work. Many conventions apply differently depending on kind. A server span and a client span for the same HTTP call describe opposite ends of the conversation and use different attributes for addresses. Teams that set kinds correctly make service maps and dependency graphs work automatically; teams that leave them as the default produce maps with missing connections.

Abstract rules become clear when you follow a single change through every stage. This walk-through uses the environment attribute, which upstream renamed in a 2024 release of the conventions.

The Situation

Your company has 300 services. Each reports its environment, such as production or staging, under an attribute whose older name was deployment.environment. Upstream conventions moved this to deployment.environment.name, and your organization decides to follow. Dozens of dashboards filter by environment, several alerts apply only to production, and a cost report groups spend by environment.

Week by Week

What Went Right

Several things made this change calm. A single Collector step gave every consumer the new name before any service had upgraded, so consumers could move early. The overlap had an owner and a date. Alerts were tested with synthetic data, not assumed. Old names were switched off in a pilot first. And the registry and schema file recorded the change, so that future tools and engineers can see exactly what happened and when.

The conventions and labels are tools. Governance is the habit of using them on purpose, together, over years.

What Governance Means Here

Governance is the set of agreements about who decides what, how decisions are recorded, how they are checked, and what happens when someone disagrees. For telemetry naming, it answers practical questions. Who may add a new attribute? What happens when two teams want different names for the same idea? How long must an old name stay available after a rename? Who tells the people who built dashboards?

Who Depends on Your Names

Many groups read telemetry, and each has its own way to fail when names drift.

The Scale Effect

With five services, a naming change means a short chat. With 400 services owned by 12 teams, it means a project. The number of possible mismatches grows with the number of producers times the number of consumers, and each mismatch is invisible until someone looks at the right chart on the wrong day. The older the system, the more people depend on accidents of naming that nobody remembers choosing.

OpenTelemetry’s conventions cover common technology. Your business has its own concepts, and they need names too.

Three Layers of Names

Use Your Own Namespace

Attributes you invent should begin with a prefix that belongs to you, such as your company or product name. This avoids collisions. If you invent payment.method today and OpenTelemetry later defines an attribute with the same name but a different meaning, your data and the standard data would become impossible to tell apart. A distinctive prefix makes such collisions practically impossible, and also lets anyone see at a glance which names are yours.

Write Naming Rules Once

A short rule sheet prevents most arguments. Good rule sheets usually cover the following points.

• Format. Lowercase words separated by underscores inside a segment and by dots between segments.
• Singular and plural. Pick one convention, and say when a list-valued attribute is allowed.
• Units. State units in the documentation and keep one unit per metric, preferably the standard base unit such as seconds or bytes.
• Cardinality. Forbid unbounded values, such as user identifiers or full URLs, as metric attributes, because each new value creates a new time series.
• Sensitivity. Mark attributes that may hold personal data and describe how they must be treated.
• Required attributes. List the few that every service must set, such as service name, environment and owner.

Keep a Registry

A registry is a structured list, kept in a code repository, of every attribute and metric your organization defines. Each entry records name, type, meaning, unit, stability, requirement level and owner. Because it lives in version control, every change has an author, a review and a history, which is exactly what governance needs. The OpenTelemetry project uses this approach for its own conventions, and its tooling, notably a project called Weaver, can work with registries that build on top of the upstream one. Check Weaver’s current documentation for exact commands and features, since the tool is young and growing.

Give Your Registry Its Own Schema URL

When your registry releases a new edition, publish it at an address that follows the same pattern as OpenTelemetry’s: a stable family path ending in a version number. Alongside it, publish a schema file recording the renames since the previous edition. Services can then label their data with your address, and Collectors can translate between your editions. Hosting can be as simple as a static website, provided that each published edition is never changed and that the address is reachable by every tool that needs to read it.

A good workflow is boring on purpose. Every change follows the same path, so surprises are rare.

flowchart TD
  A["Proposal
describe the need and the new name"] --> B["Review by naming owners"]
  B --> C["Registry updated in version control"]
  C --> D["Automated checks
validate and compare with last edition"]
  D -->|"Breaking change found"| E["Write a migration plan"]
  D -->|"Safe change"| F["Release a new edition
publish schema file"]
  E --> F
  F --> G["Roll out to services
track adoption by schema URL"]
    

The Steps in Plain Words

Roles

A Sample Decision Record

Rules that depend on people remembering them are wishes. Rules that run in a pipeline are governance.

Checks on the Registry Itself

The first group of checks looks only at the registry in version control. Validation confirms that every entry is well formed, has a type, a description and an owner, and that names follow the rule sheet. Duplicate detection catches two entries that mean the same thing. Comparison with the previous edition produces a list of added, changed and removed entries and flags the ones that are breaking. Tools in the OpenTelemetry ecosystem, including Weaver, offer commands for checking and comparing registries, and they can run custom rules written in a policy language. Confirm the current command names in the tool’s documentation.

Checks on Code

The second group looks at the programs that produce telemetry. A lint rule can flag attribute names typed by hand instead of taken from the generated constants package. A dependency rule can block imports of incubating packages in production code. Code generation from the registry gives developers ready-made constants, so correct names appear in editors through auto-complete and typos become compile errors.

Checks on Real Telemetry

Registries describe what should be emitted. The third group of checks looks at what is emitted. A live check runs an application in a test environment, captures the telemetry it produces, and compares each attribute and metric with the registry. It reports unknown names, deprecated names, wrong types and missing required attributes. This catches the cases where library upgrades silently changed names, and where developers added attributes without telling anyone.

Enforcement in the Collector

The Collector can enforce rules for the whole fleet. It can count how many items carry each schema URL, which gives you an adoption chart. It can remove attributes that are not on an approved list, redact sensitive ones, or add a missing required attribute with a default value. It can also tag data that violates a rule so that dashboards can show a compliance rate per team.

Start Gently, Then Tighten

Switching on blocking checks everywhere on day one invites rebellion. A smoother path has three stages. First observe: measure violations and publish a scoreboard without blocking anything. Then warn: show messages in code review and dashboards. Finally block: stop releases that break the most important rules, starting with required attributes and sensitive data. Each stage should last long enough for teams to fix what the previous one showed them.

A new edition does not arrive everywhere at once. For months, your fleet runs several editions side by side.

Version Skew Is Normal

Version skew means different parts of a system running different versions at the same time. In a company with hundreds of services upgraded by different teams on different schedules, skew is the permanent state. Governance does not try to eliminate it. It tries to make skew visible, bounded and harmless.

flowchart LR
  S1["Service group A
edition 1.21.0"] --> C["Collector
normalize to target edition"]
  S2["Service group B
edition 1.24.0"] --> C
  S3["Service group C
no schema URL"] --> C
  C --> B["Backend
one naming for dashboards"]
    

Define a Supported Window

Declare which editions are supported at any moment, for example “the current edition and the two before it”. Anything older is out of policy and receives reminders, then escalations. A window gives teams a predictable clock and gives the platform team a bounded set of renames to translate in the Collector.

Make the Right Thing the Default

The fastest rollout comes from changing defaults, not from asking hundreds of teams to act. A shared internal library that wraps the SDK and sets resource attributes and schema URLs correctly means each team upgrades by bumping one dependency. A standard container base image that includes a pinned instrumentation agent moves a whole fleet when the image is rebuilt. Dependency update bots can open pull requests for every repository with the new version, leaving only a review and merge for the team.

Measure Adoption

You cannot manage what you cannot see. The most valuable chart in a rollout shows, over time, the share of telemetry items carrying each schema URL, broken down by team. If your backend lets you filter by the label, build the chart there. Otherwise a counting step in the Collector can produce a metric with the schema URL as an attribute. Add a second chart of services that carry no label at all, since they are the hardest to reason about.

Handle Exceptions Openly

Some services cannot upgrade: a vendor product, a frozen legacy system, a service about to be retired. Record each as an exception with an owner and an expiry date. Exceptions without expiry dates become permanent special cases that distort every future migration.

Not every change can be a clean rename. Each kind of breaking change has its own safe route.

The Golden Rule: Never Reuse a Name

If the meaning, unit or type of a value changes, give it a new name. Reusing an old name for a new meaning is the most dangerous move in naming, because nothing looks broken: queries still run and charts still draw, but they now describe something different. A new name forces consumers to decide consciously, and leaves the old one available until they have moved.

Matching the Change to the Method

Prepare the Consumers

Breaking changes are rarely about producers. They are about the dashboards, alerts and reports built on top. Before a change begins, list every consumer you know of, search saved queries for the old names, and notify owners with a clear deadline and a description of the new names. After the change, verify that alerts still fire by sending synthetic test data through the pipeline. An alert that nobody has tested after a rename is an alert that may be silent.

Have a Way Back

Plan for rollback before you start. During overlap, rollback is easy: producers keep emitting both names, so consumers can move back. After the old names are switched off, rollback means re-enabling emission everywhere, which is slow and uncertain. Reduce risk by retiring old names in stages, first for a small group of services and then for the rest, and by keeping the switch that controls emission easy to reach.

Producers change names once. Consumers feel it everywhere. Good governance protects the readers of telemetry as much as its writers.

Why Consumers Are the Hard Part

A producer change is one code edit. A consumer change is a hunt across every dashboard, alert rule, saved search, scheduled report and spreadsheet that mentions the old name. Many of these were created by people who have since changed teams, and some live in personal folders nobody can see. The more places a name appears, the more expensive a rename is, so the first governance task is making consumers findable.

Make Queries Resilient

Several techniques reduce how much each rename hurts.

Test Alerts Like Software

An alert is a program that runs on data. Programs should have tests. Keep a small set of synthetic test signals that deliberately trigger each important alert, and run them after every naming change, SDK upgrade or Collector change. Many teams discover during an incident that a rename silenced an alert months earlier. A regular alert drill finds these problems in daylight rather than at three in the morning.

Keep an Inventory

Maintain a list of the most important consumers and which names each depends on. It does not need to cover everything, only the dashboards, alerts and reports whose failure would hurt: customer-facing alerts, service level objectives, cost reports and compliance reports. When a rename is proposed, the inventory tells you instantly whom to contact. Teams that keep this list find that migrations become routine rather than heroic.

Metrics are numbers over time, so changes in naming interact with units, buckets and the way backends store them.

The Name You Define Is Not Always the Name You See

When metrics travel to some popular backends, their names are translated into the backend’s own style. Dots in names may be replaced by underscores, a unit suffix may be added, and counters may gain a suffix marking them as running totals. A metric whose official name has dots and is measured in seconds might appear with underscores and a “seconds” ending. The exact behaviour depends on the backend and its settings, and newer versions are loosening these rules.

For governance, this means that documentation must say clearly which name is the OpenTelemetry name and how it appears in each backend you use. Alerts are written against the backend name, but changes are proposed against the convention name. Without a documented mapping, nobody can tell whether a renamed convention has affected a given alert.

Units Are Part of the Contract

A metric measured in seconds and a metric measured in milliseconds are different metrics, even if the words in their names look alike. A chart that mixes them is wrong by a factor of one thousand, and nothing in the data warns you. For that reason, unit changes should always come with a new metric name, a documented conversion, and an overlap period in which both exist. A schema file can record the rename, but the conversion must be handled by people and queries.

Histogram Buckets and Quantiles

Many duration metrics are histograms, which count how many measurements fell into each range, called a bucket. The boundaries of the buckets determine how precisely percentiles such as the 99th can be estimated. If an edition changes the suggested boundaries, data produced before and after the change cannot be combined without blurring the result, and percentile charts may show a sudden step even though nothing in the real system changed. When comparing across a migration, mark the change on charts and avoid mixing old and new histograms in one calculation.

New Attributes Create New Series

Each distinct combination of attribute values on a metric is a separate time series, which the backend must store and charge for. When a new edition adds an attribute to a widely used metric, the number of series can multiply. If the new attribute has many possible values, the effect on cost can be dramatic. Before adopting a new edition, count the series in a test environment, and use the Collector to remove or reduce attributes that you do not need.

Consistent names are not only a convenience. They are what lets privacy and security rules work at all.

Rules Are Written Against Names

Almost every control over telemetry is expressed in terms of names: “remove the attribute that holds the email address”, “never store the full URL with its query string”, “mask the database statement”. If the same fact appears under two names, a rule covering one leaves the other open. A rename can also silently bypass a rule written for the old name, so that data previously hidden starts to flow.

Opt-In Levels as Warnings

The conventions rate each attribute with a requirement level. Some are marked opt-in precisely because they may carry personal or confidential data, for example full query strings in URLs or database statements containing literal values. Governance can build on that: your registry can add a sensitivity label for each attribute, and your pipeline can use it to decide what to drop, hash or mask before data leaves a trusted network.

Review Every New Edition for Sensitivity

When a new edition of the conventions is published, its change list shows every new attribute. Add a step to your upgrade process in which someone classifies each new attribute: harmless, sensitive or forbidden. Without this step, an upgrade can introduce a field holding sensitive information, and the first sign is a privacy complaint. With it, redaction rules are updated before the new edition reaches production.

Labels as an Audit Trail

The schema URL on data tells auditors which edition of the rules applied when it was produced, and version history in the registry shows who changed what and why. During an incident review or compliance audit, you can answer questions such as “what did this attribute mean in March?” and “who approved collecting it?” from records rather than memory.

When something looks wrong after an upgrade or a rename, a short list of usual suspects explains most cases.

The Usual Symptoms

A Debugging Routine

Do Not Depend on Fetching at Runtime

Because the schema URL is a web address, it is tempting to design pipelines that download the schema file whenever new data arrives. In networks with restricted access, or when the hosting site is slow, this turns a naming feature into an availability risk. Tools that read schema files should cache them, and organizations should mirror the files they need on infrastructure they control. Applications should treat the address as an identifier and never wait on it.

Teams that manage naming well share a few habits. Teams that struggle tend to share a few mistakes.

Habits That Work

Mistakes That Teach

The right level of governance depends on who you are. These illustrative scenarios show how it scales.

Conventions keep evolving. A steady, light habit of following them is much cheaper than occasional large catch-up projects.

Follow the Releases

Each release of the conventions comes with a change log that lists additions, renames and deprecations. Assign someone, often the naming owner, to read each release and write a short summary for your organization: what is new, what is breaking, what you will adopt and when. Even a five-line note prevents the surprise of discovering a rename only when a dashboard breaks.

Choose an Upgrade Cadence

You do not need to adopt every release. Many organizations choose a regular rhythm, such as reviewing releases each quarter and moving their target edition forward once or twice a year, unless a release contains something urgent. A predictable cadence lets teams plan upgrades, lets the platform team batch translation rules, and keeps the gap between your target and upstream small enough that changes stay modest.

Take Part

The conventions are developed in the open by working groups, often called special interest groups, that welcome comments from users. If a convention does not fit your real systems, or an attribute you rely on is missing, raise it in the project’s issue tracker with evidence from your use. Early feedback during the development stage is far more powerful than complaints after stabilization, when changes are costly.

• Report mismatches. Describe the system, show the name you needed and explain why existing names fell short.
• Test early. Try development-level conventions in a safe environment and share what you learn.
• Contribute extensions. If your custom attribute is general, offer it upstream so the whole ecosystem can benefit.
• Share migration lessons. Write about what worked, so others avoid your mistakes.

Keep Vendor Neutrality in Mind

One of the biggest benefits of standard names is the freedom to change tools. Dashboards, alerts and pipelines built on standard names move between vendors with far less rework than those built on proprietary attribute names. When a vendor offers an attractive custom attribute, compare it with the standard one and prefer the standard unless the difference truly matters. Every proprietary name you adopt is a small cost of leaving later.

Every control has a price. Knowing it helps you decide how much governance to buy.

The Direct Costs

The labels themselves are almost free. A schema URL is a short piece of text attached once per resource and once per scope, not once per span, so it adds a tiny fraction to each payload and is shrunk further by compression. The costs lie elsewhere.

The Savings

The benefits are harder to see because they appear as problems that never happen. Engineers do not rebuild dashboards for each team. Alerts do not silently stop after an upgrade. Cost reports are complete. Security rules cover all spellings. Onboarding a new service takes an afternoon instead of a week of negotiation. Vendors’ built-in views work without custom configuration. For a company with hundreds of services, these savings usually exceed the costs within the first year, and they grow with every service added.

Right-Sizing the Effort

A reasonable rule of thumb is to match governance effort to how much damage a naming mistake could do. Identity attributes, required attributes and anything touching sensitive data deserve strict control. Rarely used team-specific attributes deserve light control: a naming prefix and an owner. Spending the same effort on everything wastes time, and spending none on anything invites the chaos that governance exists to prevent.

Nobody starts with a perfect system. Knowing which rung you are on tells you what to do next.

Do Not Climb Faster Than Your Needs

Higher is not always better. A small company at level two may be perfectly served, and building level-four automation for ten services is wasted effort. Choose the level that matches the number of teams, the cost of mistakes and the regulations you face. Move up when pain appears, not before, and let each rung teach you what the next one needs.

When you are ready to put these ideas to work, follow this order. Each step prepares the next.

A quick reference for the terms used in this guide.

Short answers to the questions that come up most often.

Governance via schema URLs and convention versioning is how a large organization keeps one vocabulary while that vocabulary keeps changing.

You started with a simple problem: many teams naming the same thing differently. You met the shared dictionary of semantic conventions, the schema URL that labels which edition of that dictionary data follows, and the schema file that records renames between editions. You then saw how SDKs, Collectors and backends use the label, how to migrate safely using overlap, and how registries, workflows and automated checks turn all of this into everyday practice.