Before looking at OTLP itself, it helps to understand what a protocol is and why every protocol eventually has to change.

What a Protocol Is

A protocol is an agreed set of rules for exchanging information. It says what a message looks like, what each part means, in what order messages are sent, and what to do when something goes wrong. Two programs that follow the same protocol can talk to each other even if they were written by different people in different programming languages. The rules act like a shared language.

Why Protocols Must Change

The world never stands still. New kinds of data appear, mistakes in the first design are discovered, and better ways of doing things are invented. A protocol that never changed would soon be unable to describe what people need to say. But a protocol that changes carelessly breaks every program that already speaks it. This tension between “we must improve” and “we must not break anyone” is the reason versioning exists.

The Three Questions Versioning Answers

The Real Cost of a Broken Protocol

It is easy to think of a protocol break as a small technical event, but in a large company it can mean hundreds of services losing their monitoring on the same afternoon. Engineers on call would lose traces just when a release was going out. Dashboards would turn blank, alerts would stop firing, and teams would spend hours working out whether their application was broken or merely invisible. Protocol versioning exists to make this kind of event extremely rare, and to make the unavoidable changes slow, visible and survivable.

Two Directions of Compatibility

Two terms appear again and again in discussions of versions, and they are easy to mix up. Backward compatibility asks whether a newer reader can understand data written by an older writer. Forward compatibility asks whether an older reader can cope with data written by a newer writer. A healthy protocol aims to offer both within a stable major version, because in real fleets old and new programs are always mixed together.

To talk about versions of OTLP, we first need a clear picture of what OTLP carries and how it travels.

What OTLP Is For

OTLP stands for OpenTelemetry Protocol. It is the standard way for telemetry to travel from the place it is produced to the place it is processed or stored. Telemetry here means the signals that describe how software behaves: traces, which follow a request through many services; metrics, which are numbers measured over time; and logs, which are timestamped records of events. A newer signal for profiling is also being developed.

Who Talks to Whom

In a typical system, an application uses an OpenTelemetry library, called an SDK, to produce data. The SDK has an exporter that sends the data using OTLP to a Collector, which is a program that receives, processes and forwards telemetry. The Collector then sends the data onward, often again using OTLP, to a backend that stores and displays it. Many backends also accept OTLP directly, so you may skip the Collector in small setups.

flowchart LR
  A["Application with SDK"] -->|"OTLP"| B["Collector"]
  B -->|"OTLP"| C["Another Collector"]
  C -->|"OTLP"| D["Backend that accepts OTLP"]
  A -->|"OTLP directly"| D
        

The Ways OTLP Travels

The Same Messages in Every Transport

An important point for versioning is that the messages are defined once. Whether you send them over gRPC or HTTP, in binary or JSON, you are sending the same structured data. A change to the message definition therefore affects every transport at the same time, so a single set of compatibility rules can protect everyone.

What Each Signal Looks Like on the Wire

Understanding the kinds of information each signal carries helps you picture where new fields might be added in the future. Each signal has a few core ideas, and a large number of optional details around them. The optional details are where most additions happen, because adding another optional detail is the easiest kind of change to make safely.

Metric Kinds

Metrics deserve a special mention, since they have several kinds of data point. A gauge records a value that can go up and down, such as temperature. A sum records a total that either only grows or can also fall. A histogram records how values spread across ranges, and an exponential histogram does the same with ranges that grow by a constant ratio and adapt their resolution. A summary type exists for compatibility with other systems. Adding a new kind of data point is a classic compatible change, because old receivers that do not know the new kind can ignore it.

The word “version” is used for several different things in OpenTelemetry, and mixing them up is the number one cause of confusion.

Why One Word Causes Trouble

When someone says “we are on version 1.20,” they might mean the specification, the protocol definitions, a language SDK, the Collector or the naming rules for attributes. Each of these has its own number, its own release schedule and its own stability promise. Understanding which layer a number belongs to prevents many wrong assumptions about compatibility.

Which Layers Does This Post Focus On?

The main subject is the OTLP protocol definition itself, together with its package names and endpoint paths. We will also separate it clearly from semantic conventions and schema URLs, since those are often mistaken for protocol versions. Later chapters explain how SDK and Collector upgrades connect to the protocol, because in daily work these are the versions you actually change.

OTLP is not described only in prose. It is defined precisely in files written in a schema language, and those files are the real source of truth.

What Protocol Buffers Are

Protocol Buffers, often called protobuf, is a way to describe structured data and to turn that data into compact bytes and back again. You write a definition file that lists the messages and their fields, and tools generate code in many programming languages from it. Because every language generates its code from the same definition, programs written in different languages can read each other’s messages without confusion.

Where the Definitions Live

The OpenTelemetry project keeps the OTLP definitions in a dedicated repository for protocol files, separate from the specification text and from the SDKs. The specification describes behaviour such as how to retry and how to encode JSON, while the proto files define the exact fields. SDKs and the Collector pull in the generated code for a chosen release of these files, so each build of a library is tied to a specific snapshot of the definitions.

The Shape of the Definitions

Nesting: How a Batch Is Built

A request to export data is built in layers. At the outside is an export request, which holds a list of resource groups. Each resource group holds a list of scope groups, and each scope group holds the actual items, such as spans, data points or log records. This nesting saves space, because a description of the resource is written once for many items rather than repeated on each one. It also matters for versioning, because a new field can be added at any level without disturbing the others.

flowchart TD
  R["Export request"] --> RG["Resource group: who produced this data"]
  RG --> SG["Scope group: which library produced it"]
  SG --> I1["Item: span, data point or log record"]
  SG --> I2["Item: span, data point or log record"]
        

Reading a Definition Without Fear

Proto files look strange at first, but a handful of ideas explain almost everything in them. A message is a group of named fields, much like a form. Each field has a type, a name and a number. A field marked as repeated can appear many times, forming a list. A group marked as one-of means that exactly one of several choices is present at a time. Some numbers or names can be reserved, which means they are retired and must never be used again.

Comments Matter

The comments in the definition files are a rich source of information. They describe the meaning of each field, state its stability, and explain which values are valid. When you read a definition, read the comments around any field you plan to use. They often contain notes such as when a field was added or why a particular choice was made, which gives clues about how safe it is to depend on.

OTLP uses the familiar idea of semantic versioning, and it adds stability labels that tell you which parts you can rely on.

Semantic Versioning in Simple Words

Semantic versioning uses three numbers separated by dots, such as 1.4.2. The first is the major number, the second is the minor number and the third is the patch number. The major number increases when a change can break existing users. The minor number increases when new features are added in a compatible way. The patch number increases for small fixes that change no behaviour. Reading these numbers tells you how risky an upgrade is.

The Journey Before 1.0

In its early life, OTLP was labelled with numbers beginning with zero, such as 0.9 or 0.19. Under semantic versioning, a zero major number means the design is still being shaped and breaking changes may appear in any release. During that period names changed, some message types were removed or replaced, and fields were reorganised. Once the core signals reached a stable 1.0 line, the project committed to far stricter promises, which is the world most users now live in.

Stability Labels

Beyond numbers, parts of OpenTelemetry carry a stability level. A stable part will not change in a breaking way within its major version. A part marked as in development may change at any time, including in ways that break compatibility. The core signals of traces, metrics and logs are stable in OTLP, while newer areas such as profiling have been developed under a development label, with their own package naming to make that clear.

Reading Release Notes Like a Professional

Every release of the protocol definitions comes with notes, and reading them takes only minutes. Skim for four things. First, new fields or new messages, which show what you could use. Second, deprecations, which show what you should plan to leave. Third, changes to development-stage areas, which show where instability still lives. Fourth, anything described as a breaking change, which should be rare and always deserves a careful, team-wide discussion.

Upgrading Because You Want To, Not Because You Must

Because stable OTLP is additive, there is rarely an emergency reason to upgrade the protocol definitions on a particular day. This is a gift. It lets you choose upgrade moments that suit your team, such as quiet weeks, instead of reacting under pressure. The exceptions are security fixes in the software that implements the protocol, which should still be applied promptly even though the protocol rules themselves are calm.

The promise that stable OTLP will not break you is backed by a short list of concrete rules about what changes are allowed.

What Is Allowed Within a Major Version

Within a stable major version, the project allows changes that cannot disturb existing users. New optional fields may be added to existing messages. New message types, new signals and new values for enumerations may be introduced. Documentation and comments may be improved. All of these are additive, which means that someone who ignores them still understands everything they understood before.

What Is Not Allowed

Changes that could confuse an older program are forbidden. An existing field may not be removed in a way that frees its identifying number for reuse. The meaning of a field may not be changed. A field may not change its type. Required behaviour may not be altered silently. When the project wants to retire something, it marks it as deprecated and keeps it in place, and the actual removal can only happen in a new major version.

Why Reusing Numbers Is So Dangerous

In protobuf, the number of a field, not its name, identifies it on the wire. If a field number were reused for a new purpose, an old receiver would happily read the new data as if it were the old data, giving silently wrong results instead of an obvious error. Silent wrongness is the worst kind of failure, because nothing alerts you. That is why the project treats number reuse as a hard rule.

A Quick Self-Check Before You Rely on Any Field

Before you build something important on a particular field, ask three short questions. Is the signal it belongs to marked stable, or still in development? Do the backends and tools you depend on actually read this field, or merely accept it? And will every older component on the data path behave sensibly if it never sees the field? Honest answers to these questions prevent most disappointment, because they reveal whether the field will really arrive and be used.

The compatibility promise is possible because of a few clever properties of the way protobuf reads and writes data.

Field Numbers on the Wire

When protobuf writes a message, it does not write field names. It writes each field’s number, a hint about the kind of value, and then the value itself. A receiver looks up each number in its own definition to learn what it means. This makes the messages small and fast, and it also means that names can be changed in generated code without affecting the bytes on the wire, as long as the numbers stay the same.

Unknown Fields

If a receiver meets a field number it does not know, because it was built from an older definition, it does not fail. Standard protobuf behaviour is to skip over fields it cannot understand. This is the key that makes forward compatibility possible. A newer sender can include extra information, and an older receiver simply ignores that extra information while still reading everything it does understand.

Missing Fields and Defaults

The opposite situation is also handled. If a sender is older and does not include a field that a newer receiver knows about, the receiver treats the field as absent and uses a sensible default value, such as zero or an empty string. This gives backward compatibility. Newer receivers keep working with older senders, as long as the new field was designed so that “absent” has a safe meaning.

The Limits of These Properties

Skipping unknown fields keeps the data flowing, but it does not give the old receiver the new information. If a new field carries something important, for instance a flag that changes how a span should be interpreted, an old receiver will process the span without knowing about it. This is acceptable only when the addition is designed so that ignoring it is harmless. Designers of new fields therefore ask a careful question: what happens if someone never reads this?

OTLP can also travel as JSON, and the JSON form follows its own rules that matter for compatibility.

Why JSON Exists in OTLP

JSON is easy for humans to read and for tools in places such as web browsers to produce. OTLP over HTTP therefore allows the same messages to be written as JSON text instead of binary protobuf. This is helpful for debugging, quick tests and environments where binary encoding is awkward. It is not as compact or as fast as the binary form, so most production traffic still uses protobuf.

Rules That Differ From Plain Protobuf JSON

The standard way to turn protobuf messages into JSON has some defaults that were not ideal for telemetry, so OTLP defines its own adjustments. Trace and span identifiers are written as hexadecimal text rather than the base64 text that standard conversions would produce, because hexadecimal is how engineers recognise these identifiers. Enumerations are written as their integer values, not as names, which keeps messages compatible even when names change. Field names use lower camel case.

Why This Matters for Versioning

These rules are part of the protocol’s compatibility story. Because enumerations travel as numbers and unknown fields are skipped, a JSON receiver built against an older definition continues to work when a sender starts using new fields or new enumeration values. If the rules had left names or strict validation in place, every addition could have broken JSON users. The project made these choices on purpose to keep additions safe.

OTLP does not ask the two sides to announce their versions, so everything depends on the compatibility rules working as designed.

No Version Negotiation

Some protocols begin with a greeting in which both sides say which version they speak and agree on the highest one they share. OTLP does not do this in the usual sense. A sender simply builds its message from the definitions it knows and sends it. A receiver simply reads whatever arrives using the definitions it knows. Compatibility comes from the design rules of the schema rather than from a conversation between the two programs.

The Four Meeting Cases

Because there is no handshake, it is useful to think through the four situations that can occur when a sender and a receiver were built from different minor versions of the same stable major version.

What You Gain and Lose in Case Two

Case two is the one most teams meet during rolling upgrades. A newer application sends data to an older collector. The data flows, so no alarm sounds. But any brand-new field is dropped at the first receiver that does not know it. If your goal in upgrading the application was to start sending a new field, you will not see its benefit until the collector, and every receiver after it, is upgraded too.

flowchart LR
  S["New SDK sends data with a new field"] --> C1["Old Collector: does not know the field"]
  C1 --> D["Field is dropped silently"]
  C1 --> B["Backend receives the older shape of data"]
        

How Designers Make New Fields Safe to Ignore

The rule that older programs ignore new fields only works if each new field is designed with that in mind. Designers therefore ask a set of questions before adding anything. They ask what an older receiver will do if it never reads the field. They ask whether the data would be misleading without the new field. They ask whether a sensible default exists for senders that never write it. If the answers are comfortable, the field is added as an optional extra. If not, the design is reworked.

The Add-Then-Deprecate Pattern

The safe way to replace an old design is a three-step dance. First add the better field alongside the old one. Second, mark the old one as deprecated and update documentation. Third, wait through a long period, even years, during which both exist. Only a future major version removes the old field. This slow dance may look cautious, but it is what allows thousands of independent teams to migrate on their own timelines.

The text “v1” appears in several places in OTLP, and it is worth knowing exactly what each one tells you.

Version in the Package Name

In the proto files, each group of messages lives in a package whose name ends with a version segment, such as the first generation of the trace messages. This is how protobuf projects usually signal a major version. The segment changes only when a deliberately incompatible generation is created. It means that a future second generation could exist next to the first, so old and new programs can coexist while teams migrate.

Version in the HTTP Path

When OTLP travels over HTTP, each signal has its own address path, which begins with a version segment followed by the signal name, such as the path for traces, the path for metrics and the path for logs. The version segment in these paths follows the major version of the protocol. Proxies, gateways and firewalls often route by path, so the version in the path is a handy signpost for network teams.

What a Second Generation Would Mean

If the project ever needed a truly breaking change, it would introduce new packages and new HTTP paths while keeping the old ones. Receivers could then offer both at the same time and let senders migrate at their own pace. This approach makes a large breaking change survivable, because it replaces a risky day of everyone switching together with a long, gentle transition.

Looking at real kinds of change shows the rules in action and builds an intuition for what future changes will look like.

Renames and Clean-Ups Before the Stable Line

During the zero-version era the project made several large corrections. A concept originally called instrumentation library was renamed to instrumentation scope, which better describes the part of code that produced the data. Some early metric message types were merged or removed once a simpler model was agreed. These changes were allowed because the protocol had not yet promised stability, and doing them early avoided carrying awkward names forever.

Additions After Stabilisation

Once the core signals became stable, changes took the form of additions. New optional fields were added to carry extra detail, new kinds of values were allowed in attributes, and new message types were introduced for richer metrics. Newer additions have included extra flags on spans and links to describe context more fully, and a name for log events. In each case, older programs that did not understand the addition simply ignored it.

The Design Habit Behind Additions

Behind each of these additions is a consistent habit. The proposal is discussed in the open, a careful look is taken at what happens if an older program ignores the new field, and the design is adjusted so that ignoring it is harmless. Where ignoring would cause harm, the change is delayed or reshaped. This habit is what makes the stable promise believable over many years.

Not everything in OTLP is stable, and the project deliberately gives new areas room to change before promising permanence.

Why New Areas Start as Development

Designing a data model that will serve the world for a decade is hard to do on the first attempt. The OpenTelemetry project therefore introduces new signals in a development stage. In that stage, the shape of the data can still change as real users try it and report problems. Only after enough experience does the area move to stable and receive the full compatibility promise.

How Development Parts Are Marked

Development areas are labelled in the specification and in the definitions. They may live in packages whose names signal their status, so nobody can mistake them for the stable generation. Endpoints for such signals may exist, but they carry the warning that they can change. Treating the label seriously is the best protection against surprise breakage.

A different kind of versioning travels inside OTLP messages, and it describes the meaning of attribute names rather than the shape of the messages.

Shape versus Meaning

The OTLP definitions describe the shape of messages, such as “a span has a name, a start time and a list of attributes.” But the attributes inside are just names and values, and what those names mean is decided by a separate set of rules called semantic conventions. One version of those conventions might call an attribute by one name, while a later version renames it to improve consistency. The shape of the message did not change at all, but its meaning did.

What a Schema URL Is

To help with this, OTLP messages can carry a schema URL on resource groups and scope groups. It is a web address that identifies which version of the semantic conventions the data follows. A tool that understands schemas can read the address, fetch the published list of renames between versions, and translate attribute names from one version to another. This keeps dashboards and alerts working even when different senders use different convention versions.

flowchart LR
  A["Sender with conventions version A"] --> M["OTLP message with schema URL A"]
  B["Sender with conventions version B"] --> N["OTLP message with schema URL B"]
  M --> T["Schema-aware tool translates names"]
  N --> T
  T --> D["Dashboards see one consistent naming"]
        

Why This Is Not Protocol Versioning

Surviving a Convention Rename in Practice

Semantic convention changes are the version changes most likely to hurt your dashboards, so it pays to have a routine for them. When a new SDK or instrumentation library release renames an attribute, the old name will stop appearing on new data while still existing on historical data. Queries that filter on only one name will see a sudden cliff in the charts at the moment of the upgrade.

How a receiver reports problems is part of the protocol, and it must also stay compatible as the protocol grows.

Full Success, Failure and Partial Success

When a sender exports a batch, the receiver replies. In the simplest case the whole batch is accepted. In another case the whole batch is rejected with an error. But a third case is common in real systems: some items are fine and some are not, for example because a few spans were malformed. For this, OTLP responses can include a partial success section that states how many items were rejected and gives a message explaining why.

Why Partial Success Helps Compatibility

Partial success lets a receiver say “I took what I could, and here is how many I could not use.” This is valuable during version mismatches. If a receiver refuses a few items because of a limit or validation rule, the sender can learn about it and the rest of the batch is not wasted. Because it is an optional part of the response, older senders that do not look at it continue to work without change.

Reading Warnings as Early Signs of Drift

A rising count of rejected items after an upgrade is one of the best early signs of a version problem. For example, a newer sender may send something that a stricter receiver now rejects. Watching the rejection counts on your collectors and backends, and reading the messages that explain them, helps you catch mismatches before users notice missing data.

Behaviour rules, not just message shapes, are part of the protocol, and they also need to stay stable as versions move.

Which Failures Are Worth Retrying

The OTLP specification tells senders which failures are temporary and which are permanent. A temporary failure, such as a receiver that is briefly unavailable or too busy, should be retried after a delay. A permanent failure, such as data that is invalid, should not be retried, since sending the same bad data again can never succeed. Both gRPC and HTTP have their own way of expressing this, using status codes that the specification maps to retry behaviour.

Throttling Signals

When a receiver is overloaded, it can ask senders to slow down. In gRPC it can include retry information that says how long to wait, and in HTTP it can use a standard header with a delay value. Senders are expected to respect these hints and to back off with growing delays and some randomness, so that thousands of senders do not all retry at the same instant.

Why This Matters for Versions

Because these behaviours are written into the protocol, SDKs and collectors from different times act in predictable ways toward each other. An older sender that follows the retry rules handles a newer receiver’s throttling hints correctly. A newer sender treats an older receiver’s responses in the same standard way. Predictable behaviour under stress is just as important as predictable message shapes, since failures often arrive during upgrades.

The Collector sits in the middle of most pipelines, which makes it the natural place to absorb and manage version differences.

The Collector Has Its Own Internal Model

The Collector does not simply pass bytes through. It reads incoming data into its own internal representation, applies processors, and then writes the data out again using each exporter’s format. This means the Collector’s receivers and exporters are translation points. A receiver reads the incoming protocol version it knows, and an exporter writes the outgoing version it knows. Between them, the internal model keeps things consistent.

flowchart LR
  I["Incoming OTLP from many SDK versions"] --> R["OTLP receiver reads known fields"]
  R --> M["Internal data model"]
  M --> P["Processors"]
  P --> E["OTLP exporter writes the Collector's version"]
  E --> O["Outgoing OTLP to backends"]
        

What This Means in Practice

Because of this reading and writing, a Collector acts like a normalising gateway. A fleet of applications using many different SDK versions can send to one Collector build, and the output has the shape that Collector knows. This is a big reason why platform teams like to put a Collector between applications and backends. They can upgrade the backend-facing side on their own schedule, without needing every application to move at the same time.

Information the Collector Cannot Pass Along

The same translation means that a field unknown to the Collector build is not carried through, because the Collector never stored it in its internal model. This is the same loss described earlier, and it explains why keeping the Collector reasonably current matters whenever applications start using new protocol features. The Collector sets the ceiling for how new the information flowing through it can be.

Component Stability Is Another Layer

The Collector is built from many components, and each component carries its own stability level, separate from the stability of the protocol it speaks. A component might be labelled alpha, beta or stable, which tells you how likely its settings and behaviour are to change between releases. The OTLP receiver and exporter are among the most mature, but a processor or receiver you depend on for other work may be less settled. Reading these labels is part of managing versions in your own pipeline.

Why the Collector Version Matters Even When the Protocol Is Stable

Even if the protocol never changes in a breaking way, a new Collector release can still change how a component’s settings are named or how a processor behaves. These are changes to the program, not to the protocol, and they follow their own release notes. When you upgrade a Collector, read both: the notes about the protocol definitions it bundles, and the notes about the components you use. A pipeline can break because of a renamed setting while the protocol is perfectly fine.

The order in which you upgrade matters more than the speed, and a simple rule keeps almost every rollout safe.

The Golden Rule of Ordering

Because older receivers ignore fields they do not know, the safest order is to upgrade the receivers before the senders. If receivers are upgraded first, they are ready to understand anything a newer sender might add. If senders are upgraded first, they may start sending information that the receivers silently drop. Following the flow of data backwards, from the backend toward the applications, keeps each step safe.

Canaries and Gradual Rollouts

Even safe additions deserve a gentle rollout. Upgrade a small slice of the pipeline first, such as one collector replica or one low-risk application, and compare its outputs with those of the old version. Look at accepted counts, rejected counts, latency and the shape of the stored data. If everything looks the same or better, widen the rollout.

Always Have a Way Back

A good upgrade plan includes a rollback plan written before the first change. For collectors, this usually means keeping the previous image version and configuration ready, and being able to redeploy them quickly. For SDKs, it means being able to revert the dependency and redeploy the application. Because protocol additions are compatible, rolling back a sender or a receiver is usually safe, since the older version already understands everything it did before.

Living in a Mixed Fleet for a Long Time

Few organisations ever reach a moment when every component is on the same version. Plan for mixed fleets as the normal state of affairs. Make sure that dashboards and alerts do not depend on features that only some services can produce. When you do rely on a newer field, document which services provide it, and treat missing values as expected for services still on older versions.

Trust in compatibility rules is good, but testing them in your own environment is better, since your setup always has its own quirks.

Contract Tests Between Senders and Receivers

A contract test sends a known batch of data from a sender build to a receiver build and checks what comes out. Run it for each pairing that exists in your fleet: current sender to current receiver, newer sender to older receiver, and older sender to newer receiver. The test confirms that nothing breaks and shows exactly which fields survive, which makes the silent drops described earlier visible.

Replaying Real Traffic

Sample files captured from real production traffic are valuable test material, because they contain the odd shapes that handwritten tests miss. Capture a small, safely anonymised sample, store it with its version, and replay it against new collectors and backends in a test environment. Compare the results with those from the current version to spot changes in counts, attribute names or timestamps.

Checking Definitions Automatically

Teams that maintain their own protocol definitions, or that depend on a specific release, can use automated tools to compare two versions of the definitions and report any breaking change. The OpenTelemetry project itself uses automated checks of this kind on its protocol repository, which is part of why the stable promise holds. In your own pipelines, a check on dependency updates that flags protocol definition changes gives you early warning.

Version drift means that different parts of your fleet slowly end up on different versions, and it causes most real-world protocol surprises.

How Drift Happens

Nobody plans drift. It appears because teams upgrade at different speeds, some services are rarely touched, and some images are built once and run for years. After a year, a company may have a dozen different SDK versions in production and several Collector builds. Because the stable rules keep most combinations working, drift stays invisible until a specific mismatch finally matters.

Symptoms to Watch For

Fixing Drift Gently

The fix for drift is awareness and a regular rhythm. Keep an inventory of the versions in use. Set a policy for how old a version may become. Offer teams an easy upgrade path through shared base images or automated dependency updates. Review the inventory on a schedule, and prioritise the oldest, busiest services first.

A Worked Investigation From Start to Finish

To see how these ideas fit together, follow a realistic investigation. A team upgrades one service to a newer SDK, expecting a new piece of span detail to appear in their tracing tool. Two weeks later, the detail is still missing. Nothing is failing, and nobody is sure where to look. The team follows a calm routine and finds the cause within an hour.

Naming common mistakes makes them easier to avoid in design reviews and upgrade plans.

Protocol compatibility is a shared promise, and the organisations that benefit most turn it into a short, clear policy.

What a Good Policy Contains

A useful policy fits on one page. It states which OTLP releases are supported by your backends and collectors, how many versions behind an SDK may be, who owns each layer’s upgrades, and how experimental signals are approved. It names the upgrade order and the testing required before a change is rolled out. Writing it down removes guesswork and speeds up decisions during busy periods.

Roles and Ownership

Decide who is responsible for what. A platform team usually owns the Collector tier and the backend relationship, and offers shared base images or libraries to application teams. Application teams own their own SDK upgrades within the supported range. A small group, perhaps a guild, watches upstream releases and announces changes that matter. Clear ownership prevents the common situation in which everyone assumes someone else is watching.

Measuring Version Health

A policy is only useful if you can see whether it is being followed. A few simple measures give a clear view without much effort. Count how many services run each SDK version, and how far behind the newest release they are. Count how many collectors run each build. Track the rate of rejected and refused data across the pipeline. And track how many services use any development-stage signals. Reviewing these numbers monthly turns vague worries about drift into concrete, manageable lists.

Communicating Changes Well

Most version problems are not technical failures but communication failures. A platform team upgrades a Collector without telling anyone, and application teams see unexplained changes. Prevent this with a short, regular announcement that states what will change, when, what to watch for, and whom to contact. Keep a running changelog of your pipeline’s versions, so anyone investigating a strange chart can see what changed that week.

A few realistic situations show how the ideas in this guide play out, and where the trade-offs lie.

Short, direct answers to the questions people ask most often about OTLP versioning.

Not in the usual sense. You choose a transport and encoding, such as gRPC or HTTP with protobuf, but you do not declare a protocol version. The version is determined by the definitions built into your SDK or Collector, and the compatibility rules let different versions interoperate.

Yes, within a stable major version. The older Collector skips fields it does not know and processes the rest. The cost is that any brand-new information in the message is lost at that Collector, so you only get the full benefit once it is upgraded.

Yes. The newer Collector treats fields that were never sent as absent and uses default values. Features that depend on newer fields simply will not be present for that data, but nothing fails.

It identifies the major generation of the protocol for that signal’s address. It changes only for deliberately incompatible generations. Minor additions do not change it, which is why proxy rules written for these paths keep working across many releases.

No. The specification, the protocol definitions, the SDKs and the Collector each have their own version numbers and release rhythms. They influence each other, but a number from one layer says little about another layer.

It identifies which version of the semantic conventions the data follows, so tools can translate renamed attributes between versions. It is about the meaning of names, not the shape of messages, and it is separate from protocol versioning.

Traces, metrics and logs are the core stable signals. Newer areas such as profiling have been developed under a development label. Always check the current specification for the exact status, since stability levels change as the project matures.

OTLP adjusts a few defaults to suit telemetry. Identifiers are written as hexadecimal, enumerations as numbers and unknown fields must be ignored. These choices keep the JSON form readable and compatible as the protocol grows.

Look for the partial success information in the response, which gives a count of rejected items and a message. Make sure your exporters or collectors log it, and watch the rejected counts on your pipeline dashboards.

Upgrade receivers before senders. That means the backend first, then gateway collectors, then node agents, then SDKs, with checks and a pause after each stage. This order ensures new fields are never sent to something that cannot read them.

Only if a change is needed that cannot be made compatibly, and the project has designed the packages and paths so that a second generation could run beside the first during a long transition. Nothing in your current setup requires you to plan for that today.

Attach SDK and Collector versions as resource attributes on your telemetry and query them, keep a simple inventory, and set a policy for maximum age. Automated dependency updates and shared base images also reduce drift without much manual work.

Rejecting them would make every new field a breaking change, because any addition would instantly stop older receivers from working. By skipping what they do not understand, older receivers allow the protocol to grow gradually. This is a deliberate design choice, and it is the heart of the forward compatibility promise.

Deprecated means the item still exists and still works, but the project asks people to stop using it because it will be removed later. Removed means it is gone. Within a stable major version, items are only deprecated. Removal can happen only in a new major version, with a long warning period beforehand.

No. Compression, such as gzip, is applied to the bytes after the message is built and removed before the message is read. It is independent of the message definitions, so the compatibility rules for fields apply equally whether compression is used or not.

Not always. Each SDK release bundles a particular snapshot of the definitions, and it may take time before a new field is supported in every language. This is why capabilities differ between languages, and why you should check the documentation of each SDK you use for the features it supports.

A backend should accept the stable signals, ignore unknown fields, return clear partial success information, follow the retry and throttling rules, and document which optional fields it uses. Following these simple habits lets customers send data from a wide range of SDK and Collector versions without surprises.

Yes. Because both transports carry the same messages, you can use gRPC on one hop and HTTP on another. A Collector can receive on one and export on the other. Versioning rules are the same either way, so you can choose transports for operational reasons such as network policy.

Send a test message that contains the field and look at what appears in the stored data or in the receiver’s debug output. Documentation helps, but a real test is the most reliable answer, since a receiver can accept a field without making any use of it.

Upgrade in the order of receivers first, then senders, and check the data at each stage. This one habit prevents most silent data loss, and it works across every version change you will ever meet, big or small, protocol, collector or SDK.

OTLP versioning is the set of rules that lets the OpenTelemetry Protocol grow without breaking the programs that use it. The protocol is defined in proto files and follows semantic versioning, with stable signals promising only additive changes within a major version. Protocol Buffers make this possible through numbered fields, skipping of unknown fields and sensible defaults for missing ones. The JSON form follows adjusted rules that preserve the same compatibility.

There is no version handshake, so safety comes from the schema rules, the package and path naming, the stability labels and your own upgrade discipline. Treat the protocol version, the semantic convention version and the SDK and Collector versions as separate things. Upgrade receivers before senders, test the pairings in your fleet, watch for rejected data, and keep a short, written version policy. If you do these simple things, protocol changes become routine events instead of emergencies.

Perhaps the most reassuring lesson is that the system was designed with human reality in mind. Teams upgrade at different speeds, services linger on old releases, and mistakes happen. The compatibility rules, stability labels and gentle deprecation process exist precisely so that ordinary organisations can keep their telemetry flowing through all of this. Learn the rules once, write them into a short policy, and you can treat each new release as an opportunity instead of a threat.