OpenTelemetry Python: the API and SDK split, and what it costs you

The problem: Python telemetry that outlives your backend choice

Instrumentation written directly against a vendor SDK is expensive to remove. Every span call, every metric counter, every attribute name is tied to one backend's client library, and switching backends means editing application code rather than configuration. OpenTelemetry Python exists to break that coupling. The repository splits into two installable packages: opentelemetry-api, which the README describes as abstract classes and no-op implementations following the OpenTelemetry specification, and opentelemetry-sdk, described as the reference implementation of the API. The intended audience is two distinct groups. Library authors, who should depend only on opentelemetry-api so their code emits telemetry without forcing a backend on anyone. And application developers, who depend on opentelemetry-sdk or another package that implements the API, and thereby choose where the data goes. That split is the whole point of the project. If you only ever build one internal service with one observability vendor, the abstraction looks like overhead. If you maintain a library that other teams install, it is the difference between shipping telemetry and shipping a dependency conflict.

How the API and SDK divide the work at runtime

The mechanism is a global registration step. Application code calls into the API. The API holds abstract classes and no-op implementations, so a process with no SDK configured still runs: spans are created, attributes are set, and nothing is exported. When the SDK is installed and configured, it registers itself as the implementation behind those API calls, and the same call sites start producing real spans and metrics that get batched and handed to an exporter. Two consequences follow. First, a library that depends only on opentelemetry-api can be installed into an application that has no SDK at all, and the library's instrumentation costs effectively nothing. Second, the choice of backend lives in the application's configuration, not in the library's source. The repository layout mirrors this: opentelemetry-api, opentelemetry-sdk and opentelemetry-semantic-conventions sit at the top level alongside exporter/, propagator/ and shim/ directories, each holding separately installable packages. Context propagation is a separate concern again, handled by packages under propagator/, which is why the install instructions treat exporters and propagators as their own installs rather than part of the core.

Installing OpenTelemetry Python and emitting a first span

The README gives the install commands directly. Both packages come from the Python Package Index, so a plain pip install is enough for the core:

pip install opentelemetry-api
pip install opentelemetry-sdk

Libraries should take only the first line. Applications need both, plus an exporter. Exporters are not bundled with the SDK; the README points at the exporter/ directory and gives this pattern:

pip install opentelemetry-exporter-{exporter}

The braces are a placeholder in the README itself, not a package name. You substitute a real exporter from the exporter/ directory, for example opentelemetry-exporter-otlp-proto-http or opentelemetry-exporter-prometheus, both of which appear in the repository's own dependency list. Propagators install the same way, with pip install opentelemetry-propagator-{propagator}. If you want to work against unreleased code instead of PyPI, the README describes an editable install from a clone:

pip install -e ./opentelemetry-api -e ./opentelemetry-sdk -e ./opentelemetry-semantic-conventions

Note the version floor. The repository's pyproject.toml sets requires-python to >=3.10, and the README states the project adds support for new Python versions no later than three months after they become stable, and removes support for old ones six months after end of life. For a working example rather than a from-scratch walkthrough, the README sends readers to the getting started guide at opentelemetry.io and to the instrumentation documentation for manual API usage and SDK setup. The repository itself does not carry a runnable hello-world in the README.

Logs are the weak signal, and the README says so

The project status table is unusually blunt. Traces are Stable. Metrics are Stable. Logs are listed as Development, marked with an asterisk that expands into a warning: stabilizing the Log signal would require making deprecations and breaking changes, and the maintainers say they will try to reduce the releases that may require an update to your code, especially for instrumentations or for SDK developers. Read that as a real constraint rather than boilerplate. If your reason for adopting OpenTelemetry Python is to unify logs with traces under one SDK, you are adopting the least settled part of the project, and the README explicitly reserves the right to break it. A second limitation is structural: the core repository is not where most instrumentation lives. The README directs readers to the separate opentelemetry-python-contrib repository for additional exporter and instrumentation packages. That means the auto-instrumentation you probably want for a web framework is not installed by the two pip commands above, and its release cadence is governed by a different repository than the one you are reading. The version numbers reflect the split too. Releases are tagged with two versions, such as v1.44.0 alongside 0.65b0, where the leading 1.x line and the 0.x beta line track packages at different stability levels.

Where OpenTelemetry Python is the wrong tool

If you run a single Python service and you are happy with your vendor's agent, the API/SDK split buys you nothing today and costs you a configuration surface. The no-op default is also a trap in the other direction: a process with the API installed but no SDK configured will accept every span call and export nothing, with no error. Silent no-ops are the correct design for a library, and a genuinely confusing debugging experience for an application, because the failure mode is absence of data rather than an exception. Teams that do not yet export telemetry anywhere will find the setup cost hard to justify. There is also the versioning cost. The README's warning about breaking changes during log stabilization applies most sharply to SDK developers and instrumentation authors, which is exactly the group most likely to pin to a specific minor version and read the changelog before every bump. The repository does carry a CHANGELOG.md and a RELEASING.md, and rationale.md documents the versioning and stability guarantees, so the information exists, but it is on you to read it.

The alternative: vendor agents and framework-specific tracing

The obvious alternative is a vendor's own Python agent, installed as a single package that instruments your framework and ships data to that vendor's backend with no intermediate abstraction. The difference is where the coupling sits. A vendor agent puts the backend choice inside the library you import, which is faster to start and harder to reverse. OpenTelemetry Python puts the backend choice in the application's configuration, behind an API that libraries can depend on safely. A second alternative is framework-native tracing, where the web framework or its ecosystem provides hooks that feed one specific tracing system. That approach fits a monoculture and fragments the moment you add a second language or a second backend. The propagator packages in this repository show the practical difference: Jaeger and B3 propagators are installable as separate packages, so the wire format your services use for context is a choice you make rather than a property of the SDK. Neither alternative is wrong. They are simply optimised for different lifetimes, and the OpenTelemetry bet only pays off if your instrumentation outlives your current backend.

Licence, maintenance and upgrade cost

The repository is licensed Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, and it is the same licence the wider OpenTelemetry project uses, so combining this SDK with vendor exporters does not introduce a copyleft obligation from this side. It is not legal advice; check your own compliance process. On maintenance, the last push to the default branch was on 2026-09-24, and the most recent release listed is v1.44.0 from 2026-07-16. The repository is not archived. Active development is visible in the release cadence: v1.43.0 in June 2026 and v1.42.1 in May 2026, with the 0.x beta line moving alongside. Upgrade cost is the part worth budgeting for. The README warns that log stabilization will bring deprecations and breaking changes, and the dual version numbering means the 1.x and 0.x lines can move independently. A dependency on opentelemetry-api alone is cheap to keep current, since it is the stable surface. A dependency on the SDK plus several exporters and instrumentation packages is where the pinning and changelog reading actually happens.

Editorial conclusion

Adopt it when you want vendor-neutral tracing and metrics in Python and can live inside the API/SDK split: libraries depend on opentelemetry-api only, applications pick opentelemetry-sdk plus an exporter. Do not adopt it expecting a finished logging story, because the README marks Logs as Development with breaking changes still planned. Before you commit, read rationale.md for the versioning and stability guarantees, check the exporter directory for the backend you actually use, and confirm which Python versions your runtime supports against the project's stated removal policy.

Frequently asked questions

Official sources

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