OpenTelemetry works in many programming languages. Something must keep them all consistent.

OpenTelemetry, often called OTel, is an open standard and a set of tools for producing telemetry. Telemetry means data that software sends out about its own behavior, such as traces, metrics and logs. What makes OpenTelemetry special is that it exists for Java, Python, Go, JavaScript, .NET and many other languages, all at once, and all of them are expected to behave in the same way.

Think about what could go wrong without a shared rulebook. A trace started in a Java service must be understood by a Go service that receives the request. A metric named one way in Python must mean the same thing when it arrives from a .NET program. If every language team made its own private decisions, data from different programs would not fit together, and the whole promise of a single, vendor-neutral standard would collapse.

What a specification gives you

A specification is not code. It is a written description of behavior: what an operation must do, what it may do, and what it must never do. Implementations in each language then follow that description. Because behavior is described once, centrally, a change to the rulebook becomes a coordinated change across the whole ecosystem, and that is exactly why changing it must be done carefully.

A short glossary makes everything after this chapter easier to follow.

A tour of the rulebook and the place where it is kept and changed.

The specification lives in a public repository on GitHub, a website where programmers store and collaborate on text and code. The repository holds the cross-language requirements that every OpenTelemetry implementation is expected to meet. The written documents are in a folder named for the specification, and the latest released version is also published on the project website for easy reading.

The main areas covered

Two neighbors worth knowing

Two closely related things live nearby but are managed a little differently. The first is the folder of enhancement proposals, the OTEPs, which also sits in the specification repository and holds the design documents behind big changes. The second is the set of semantic conventions, the agreed names for common labels, which are maintained as their own project and repository because they change at a different pace than the core rules.

Versioning of the rulebook itself

The specification follows semantic versioning, a widely used numbering scheme in which the version number tells you how big a change is. Every release has a written changelog listing what is new, what changed, and what was removed. A compliance matrix, kept alongside the specification, records how well each language implementation follows each requirement, which is a practical way for users to see where their language stands.

A process is only as good as the people and bodies who run it.

OpenTelemetry is run by volunteers and employees of many companies who contribute to a shared project. No single company owns it. Decision making is spread across several groups, each with a clear area of responsibility. Understanding who does what helps you know where to take an idea and who to ask for help.

flowchart TD
  GC["Governance Committee: community health, scope, repositories"] --> TC["Technical Committee: technical direction and spec changes"]
  TC --> SPEC["Specification SIG: maintainers and sponsors"]
  TC --> LANG["Language SIGs: SDK maintainers and approvers"]
  SPEC --> CONTRIB["Contributors: anyone with an idea"]
  LANG --> CONTRIB
        

The groups, in plain words

The key design idea is the separation between governance and technical authority. The Governance Committee deliberately does not decide technical questions. It charters the Technical Committee, which in turn works with the SIGs. This keeps arguments about how the community is run apart from arguments about how the software should behave.

Rules about who can serve are what keep one company from steering the whole project.

A shared standard is trustworthy only if no single organization can bend it to its own advantage. OpenTelemetry therefore builds diversity rules directly into its committees and its review process. These rules are one of the least visible and most important parts of the specification process.

The Governance Committee

The Governance Committee has nine members elected for staggered two-year terms, so the whole committee never changes at once. Voters are community members with standing, which means people with a meaningful number of contributions in the previous year, plus all approvers and maintainers. Candidates need endorsements from people at different companies, and no more than two members of the committee may come from the same company. Elections use approval voting, where each voter can approve any number of candidates and the most approved candidates win.

The Technical Committee

The Technical Committee works differently. Members are not elected on a fixed calendar. Instead, a new member is nominated by a community member in good standing, sponsored by existing members, and approved by a super-majority vote of more than two-thirds. The committee must keep a minimum number of members, and no more than a quarter of the members may work for the same employer. Members who stop participating are removed automatically, which keeps the committee active.

The same idea at review time

The diversity principle appears again when changes are reviewed. As we will see, a specification change needs approval from code owners who represent different companies. A change that only one company’s staff are willing to support is, by design, harder to merge than one that experts from several organizations agree on.

Not every change deserves the same ceremony. The process scales with the risk.

Imagine a hospital where fixing a typo on a poster, buying a new type of bandage and building a new surgical wing are all treated with the same paperwork. Either the typo would take a year or the new wing would be approved in a day. The specification process avoids this by sorting changes into three sizes, each with its own path.

flowchart TD
  I["You have an idea"] --> Q{"How big is the change?"}
  Q -->|"Typo, clarity, broken link"| T["Trivial: open a pull request directly"]
  Q -->|"New term, optional parameter, stabilizing a feature"| S["Smaller: get an issue approved first"]
  Q -->|"New signal, new metric type, cross-cutting system"| O["Significant: write an OTEP"]
  T --> R["Review and merge"]
  S --> R
  O --> D["OTEP approved, then spec pull request"]
  D --> R
        

When you are unsure which size your idea is, ask in the specification channel. Maintainers would much rather help you choose the right path early than see good work stall because it was started on the wrong one.

The everyday path that most contributions follow.

Trivial changes, step by step

Smaller modifications, step by step

When a change will ripple through every language, a written design comes first.

An OpenTelemetry Enhancement Proposal, shortened to OTEP, is a document that explains a big idea before it is turned into rules. It exists for what the project calls cross-cutting changes: changes that affect multiple languages and implementations by introducing new behavior, modifying existing behavior or changing requirements. Typical examples include a new type of metric, new information attached to every span, a new way to configure tracers, or a change to how extensions work.

When an OTEP is not needed

Bug fixes, documentation improvements, internal refactoring and changes that affect only one language do not need an OTEP. The test is simple: would this change force several implementations to change what they do? If yes, you probably need an OTEP. If it stays inside one language or merely clarifies existing text, you probably do not.

What a good OTEP contains

From a blank template to an approved design, and then into the rulebook.

sequenceDiagram
  participant A as Author
  participant R as Reviewers
  participant S as Spec maintainers
  participant L as Language SIGs
  A->>A: Copy the template and write the proposal
  A->>R: Open a pull request in the oteps folder
  R->>A: Comments, questions, alternatives
  A->>R: Revise the document
  R->>S: Required approvals given
  S->>S: Merge the OTEP as approved
  S->>A: Integration issue opened for the spec text
  A->>S: Spec pull request with prototypes
  S->>L: Implementation issues created in each project
        

Step by step

Two simple rules do a surprising amount of the work in keeping quality high.

For the specification itself, the contribution guide sets out firm review rules. These rules are intentionally simple so that everyone can predict what will happen to a pull request, and they are designed to protect the standard against hasty or biased decisions.

Rule one: approval from different companies

A change needs approval from at least two code owners who represent different companies. A code owner is a person trusted to approve changes in an area. Requiring two different companies means no single employer can quietly push through a change that mainly serves itself. It also doubles the chance that a mistake will be noticed, because reviewers bring different experience.

Rule two: a cooling-off period

After the last modification to a pull request, it must wait at least two working days before it can be merged. Trivial fixes are the usual exception. This waiting time exists because the community is spread across the world. A change made in one time zone should not be merged before reviewers in another time zone have had a fair chance to wake up, read it and object.

What happens when a change is stuck

Sometimes a proposal stalls because experts disagree or nobody is sure. The guide suggests that the author summarize the different viewpoints in the description of the pull request and mention the relevant experts so they can respond. If nothing moves, the author can raise it in the specification channel or at the weekly specification meeting, typically after waiting around two weeks. Escalation beyond that goes to the Technical Committee through a public issue that lays out the trade-offs.

The project prefers rules that have been tried over rules that merely sound good.

A written rule can look perfect on paper and still turn out to be awkward, slow or impossible in real code. To avoid such surprises, the specification process asks for prototypes. A prototype is a working sample implementation that shows the proposed behavior really can be built and used.

How much proof is required

Why several languages for stability

Different languages have different strengths and limitations. A design that is natural in one language may be clumsy in another. Languages without certain features may expose a flaw that the first prototype never revealed. Requiring multiple prototypes before stability drags those hidden problems into the open while changes are still cheap.

Every part of OpenTelemetry carries an honest label about how far you can trust it.

Not every feature is equally finished. A brand-new capability might still change shape next month, while a mature one is promised not to break for years. To avoid confusing users, the specification describes a life cycle with clear maturity levels. These labels are one of the most useful things to understand if you are deciding whether to build on a feature.

flowchart LR
  D["Development: may change, even in breaking ways"] --> S["Stable: formal compatibility promises"]
  S --> P["Deprecated: replacement exists, same support as stable"]
  P --> R["Removed: leaves the specification, major version change"]
        

Why a replacement must exist first

The rule that deprecation requires a stable replacement protects users from being stranded. Nobody is told to stop using something unless there is a supported alternative ready for them. This single rule prevents a whole class of painful forced migrations.

What exactly does the project promise when it calls something stable?

Stability is only meaningful if it is spelled out. The specification lays out concrete promises about what will not break, how version numbers signal the size of a change, and how long old versions will continue to receive fixes.

The core promise

Once an API is stable, all existing calls must continue to compile and work against every later minor version of the same major version. Software that works today with a stable API should keep working after routine upgrades. Plugin points that the SDK offers, and the constructors people use to create SDK components, must also remain backward compatible. For languages that distribute compiled binaries, binary compatibility is expected to be preserved as well.

How version numbers speak

Stable API and SDK packages for one language share a unified version number so that users do not have to guess which versions fit together. Contributed extension packages are versioned independently, and the separate component families, such as the API, the SDK and the semantic conventions, can each increase their own numbers on their own schedule.

How long old versions are supported

Names matter, and renaming something safely is a surprisingly deep problem.

Semantic conventions are the shared dictionary of names used on telemetry: the label for an HTTP method, the name of a database operation, the way a cloud region is recorded. Dashboards, alerts and analysis tools all read these names. If a name changes without warning, dashboards silently go blank and alerts stop firing.

Stable names cannot simply change

Once a name is stable, the project promises not to alter it in ways that would break existing analysis. Instead, evolution is handled through a mechanism of schema transformations. A schema transformation is a machine-readable description of how to convert data from an older naming scheme to a newer one. Allowed evolutions include renaming an attribute or a metric and adding new attributes, with the transformation recorded so that tools can translate.

Why this has its own home

Semantic conventions evolve faster than the core rulebook, because new technologies and new kinds of systems keep appearing. Giving them their own repository and their own working group lets the community add, refine and stabilize conventions for databases, messaging, cloud platforms and many other areas without slowing the core specification down. The same overall habits apply: proposals, review by experts across companies, maturity levels and compatibility rules.

A rule on paper only matters once the implementations follow it.

After a specification change is merged, the real work of spreading it begins. The specification SIG does not write every language’s code. Each language SIG owns its own implementation and decides how and when to adopt the new behavior, guided by the specification and the issues created for them.

Configuration gets special care

Because users want to configure every language in the same way, SDK configuration is described by a shared declarative schema. When a specification change alters configuration, the matching schema change must be approved and merged together with it, so the written rule and the machine-readable configuration never drift apart.

Open work needs open places to talk.

The specification process is public by design. Discussions happen in writing, in recorded or documented meetings, and in shared chat channels, so anybody can follow the reasoning behind a decision and anyone can take part.

How the Technical Committee decides

The committee prefers to reach agreement through discussion and uses a vote only when consensus cannot be reached. A vote needs a quorum of more than half of the members and a simple majority to pass, and the results are shared publicly. Meetings are open to observers and are documented, which keeps decisions accountable.

Follow a made-up proposal from first spark to widespread use.

To make everything concrete, imagine that a contributor notices that many users struggle to measure how long their programs spend waiting in queues. They believe a new kind of measurement would help. This story is invented to show the path, not a record of a real proposal.

Notice how many separate checkpoints protect the final result: agreement on the need, a written design, wide review, a working prototype, diversity of approvers, a waiting period, early feedback and multi-language proof. Each checkpoint catches a different kind of mistake, and none of them depends on a single person or company.

Every rule in the process answers a specific fear.

Advantages and trade-offs

The slowness is a conscious price. A standard that thousands of companies depend on cannot be edited like a private notebook. The project accepts slower progress in exchange for decisions that survive scrutiny and rarely need to be reversed.

Common ways good ideas get stuck, and how to avoid them.

A practical checklist for anyone who wants to contribute.

Best practices

Common mistakes

Answer a few questions and find the right path.

flowchart TD
  S["You want to change something"] --> Q1{"Is it only a typo, wording fix or link?"}
  Q1 -->|"Yes"| A["Open a pull request directly"]
  Q1 -->|"No"| Q2{"Will several languages have to change behavior?"}
  Q2 -->|"No"| Q3{"Is it a new term, optional parameter or stabilization?"}
  Q3 -->|"Yes"| B["Open an issue, get approval, then a pull request with a prototype"]
  Q3 -->|"No"| C["Likely a language-specific matter, take it to that SIG"]
  Q2 -->|"Yes"| D["Write an OTEP first"]
  D --> E["Then a spec pull request with prototypes, changelog and config schema updates"]
  E --> F["Later, gather multi-language prototypes to reach stability"]
        

Treat the guide as a starting point. Maintainers have the final word on the path and the number of prototypes, so a short conversation before you begin is the best investment you can make.

You do not need to be an expert to begin helping.

Short, direct answers to the questions people ask most.

The specification is a written description of required behavior, independent of any language. An SDK is real software in one language that follows that description. The specification tells implementers what to build, and the SDK is the result.

No. Trivial fixes need only a pull request, smaller modifications need an approved issue first, and only significant, cross-cutting changes need an enhancement proposal.

At least two code owners representing different companies must approve, and the change must wait the minimum period after its last modification. The Technical Committee provides technical direction and handles escalations.

Because designs that look good on paper can fail in real code. A prototype exposes practical problems cheaply, and several prototypes in different languages expose problems that one language would hide.

It means the feature is new and may still change, possibly in breaking ways. It can become stable later without disrupting existing users, but you should not depend on it for long-lived critical systems without accepting the risk.

The stability rules describe at least three years of support for an API after its successor major release, and at least one year for SDKs and contributed packages, with fixes backported during that time.

Stable names are not changed in ways that break existing analysis. Evolution is handled through schema transformations that describe how to translate between old and new names.

Summarize the different viewpoints in the description and tag the relevant experts. If there is still no movement after about two weeks, raise it in the specification channel or at the weekly meeting. Unresolved technical disputes can be escalated to the Technical Committee.

No. The Governance Committee handles community, scope, values and repositories. Technical decisions belong to the Technical Committee and the SIGs, which keeps governance debates separate from technical ones.

Because reviews require approvers from different companies, and the committees limit how many members may share an employer. These rules are meant to keep the standard neutral.

The compliance matrix in the specification repository tracks how each language implementation meets each requirement, and the project status page shows the maturity of signals and components.

No. Governance and contribution documents are revised as the project learns. Always read the current contribution guide in the repository before starting, since details such as numbers of approvals or locations of documents can be updated.

The rulebook and the teams that build the software teach each other constantly.

It is tempting to picture the specification as a top-down order handed to language teams. In practice the relationship runs in both directions. The specification group collects lessons from implementers, and implementers rely on the specification for direction. Understanding this two-way flow explains why the process values prototypes, open meetings and wide review so highly.

What the specification group contributes

The specification group offers clarity and consistency. It looks across all languages at once and notices when two teams have solved the same problem in different ways. It writes down a single answer so that users never have to wonder whether a feature behaves differently depending on the language. It also acts as a referee, helping teams find common ground when their preferences differ.

What the language teams contribute

Language teams contribute reality. They know which ideas are easy in their language and which are painful, and they hear directly from users about what breaks. Many of the best specification changes began as a language team’s complaint that the written rule was ambiguous, impossible to follow efficiently, or missing a common situation. Without that feedback, the specification would drift away from real needs.

Typical moments of collaboration

Healthy tension, not conflict

Disagreements between the specification group and a language team are normal and often productive. A language team may argue that a rule is too heavy for its runtime, while the specification group argues that consistency across languages matters more. The escalation paths exist for exactly these moments, and the habit of writing down each side’s reasoning means that even a disputed decision can be understood and revisited later.

The OpenTelemetry specification is the shared rulebook that keeps many language implementations consistent, and the specification process is the careful, public, multi-company method for changing it. Small changes travel a light path, medium changes need an approved issue first, and significant cross-cutting changes begin with a written enhancement proposal. Every non-trivial change needs reviewers from different companies, a waiting period for time zones, and proof in the form of working prototypes.

Features then move through maturity levels from development to stable, and stability carries strong compatibility and long-term support promises that explain why the bar is high. Governance is split between a Governance Committee for community matters and a Technical Committee for technical ones, both bound by rules that prevent any single company from dominating. Understanding these steps lets you read the specification critically, judge the maturity of what you depend on, and, if you wish, take your own idea all the way from a casual suggestion to a rule that the whole ecosystem follows.