OpenTelemetry Python ships a stable line and a beta line from one tag

One tag, two versions, one stable and one beta

The release history has a shape worth noticing. The three newest releases are tags whose names are bare version numbers, but whose titles carry two of them. The first is titled with a stable one and a beta one on either side of a slash, the second the same one step down, the third one step down again. So a single tag publishes two artifacts: the current stable version of the API and SDK, and the corresponding pre-one point-oh version on the beta stream. That is why the version numbers in this project do not advance in a single sequence, and it is why a dependency constraint written against one stream says nothing about the other. The stability guarantees themselves are documented in a separate file at the repository root rather than in the readme.

Traces and metrics are stable, logs are still in development

A three row table states the project's status honestly. Traces are marked stable, metrics are marked stable, and logs are marked as in development with a footnote. The column for which repository owns the signal reads as not applicable in all three rows, because this repository is the language implementation rather than the specification or the collector. The footnote is the important one. The project says it is working on stabilising the logs signal, that doing so will require deprecations and breaking changes, and that it will try to reduce the number of releases which force an update to your code, with instrumentations and SDK developers called out as the audience it is trying to protect. Traces and metrics carry no such warning.

The API package ships no-ops so libraries need not choose an SDK

The install section explains the dependency rule in two sentences, and it is the single most useful thing on the page. The API package contains abstract classes and no-op implementations written against the OpenTelemetry specification. The SDK package is the reference implementation of that API. A library that produces telemetry should depend only on the API package and defer the choice of an SDK to the application developer, while an application may depend on the reference SDK or on another package that implements the same API. The consequence is concrete: instrumenting a library costs your users an API dependency and nothing more, and no code path in your library has to know which vendor's SDK will be present at runtime. The install itself is two commands, one for each package:

pip install opentelemetry-api
pip install opentelemetry-sdk

New Python versions arrive in three months, old ones leave in six

Interpreter support is stated as a policy rather than a list, which is the right way round for a project with this many dependants. The rule is that the project tracks currently supported Python versions, adding a newly released version no later than three months after it becomes stable and removing support for an old version six months after that version reaches its end of life. The manifest floor is consistent with that, requiring Python 3.10 or newer rather than naming individual interpreters. For an application team this means your upgrade window is bounded from both directions and that the removal half is the one that will eventually break a pinned environment, six months after a Python release stops receiving fixes.

The root manifest is a workspace, not something you can install

The manifest at the repository root is not a package, and it says so twice. Its version field is set to zero point zero point zero with a comment stating that the value is not used, and the workspace settings mark the project as not being a package while requiring a minimum version of a specific workspace tool. Its dependency list is not external dependencies either. Every entry is a local package name, from the API and SDK through the semantic conventions, the protocol packages, the test utilities and about a dozen exporter and propagator packages, and every one of them is mapped to a workspace source. So the root file exists to make the repository installable as a whole for development, and installing this project means installing one of the directories inside it.

Exporters install one at a time with a placeholder in the command

Two directories hold the optional distributions, and both are installed with a command that contains a placeholder rather than a real name. The exporter directory installs with a package name built from a fixed prefix and a brace-delimited exporter slot, and the propagator directory does the same with a propagator slot. Reading the manifest tells you what actually exists: JSON output to a file, JSON over HTTP, a shared HTTP transport, the OTLP protocol over gRPC and over HTTP with their shared and common helpers, a Zipkin JSON exporter, a Prometheus exporter, and B3 and Jaeger propagators. For development installs, three directories are named explicitly in an editable install command, and everything else in the project lives in a separate contrib repository.

A weekly call, published notes, and a named approver list

The governance section is unusually complete for a library. There is a weekly meeting on Thursdays at a fixed hour Pacific time, with the caveat that the slot changes depending on contributors' availability, a public calendar for the dates and links, and meeting notes kept in a public document rather than a private one. The stated invitation is open regardless of experience level. Below that sit two named lists. Five maintainers are named with their employers, which are Google, an independent contributor, Microsoft, Oracle and Elastic. Eight approvers follow, attributed to Dash0, Google twice, Microsoft, Honeycomb, Splunk, a tracing company and SolarWinds. Then an emeritus section listing people who held those roles and left, which is the sign of a project that has outlasted several of its own governance generations.

Editorial conclusion

OpenTelemetry Python is the right dependency if you are writing a library that emits telemetry, because the API package installs with no-op implementations and leaves the choice of an SDK to whoever runs the application. Three things to know before you pin a version. Read the logs signal's status, since it is explicitly in development and the project has said stabilising it will require deprecations and breaking changes. Expect to track two release streams, because a single tag publishes both the current stable version and a beta. And check the Python floor against your own environment, since support for a new interpreter arrives on a three month deadline and old ones are removed on a six month one. What this repository is not is a distribution channel for instrumentation, which lives in a separate contrib project.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. open-telemetry/opentelemetry-python on GitHub
3. Project website
4. README
5. Releases