pytest-opentelemetry
Instruments your pytest runs, exporting the spans and timing via OpenTelemetry.
Why instrument my test suite?
As projects grow larger, perhaps with many contributors, test suite runtime can be a significant limiting factor to how fast you and your team can deliver changes. By measuring your test suite's runtime in detail, and keeping a history of this runtime in a visualization tool like Jaeger, you can spot test bottlenecks that might be slowing your entire suite down.
Additionally, pytest makes an excellent driver for integration tests that operate
on fully deployed systems, like your testing/staging environment. By using
pytest-opentelemetry and configuring the appropriate propagators, you can connect
traces from your integration test suite to your running system to analyze failures
more quickly.
Even if you only enable pytest-opentelemetry locally for occasional debugging, it
can help you understand exactly what is slowing your test suite down. Did you
forget to mock that requests call? Didn't realize the test suite was creating
10,000 example accounts? Should that database setup fixture be marked
scope=module? These are the kinds of questions pytest-opentelemetry can help
you answer.
pytest-opentelemetry works even better when testing applications and libraries that
are themselves instrumented with OpenTelemetry. This will give you deeper visibility
into the layers of your stack, like database queries and network requests.
Installation and usage
pip install pytest-opentelemetry
pytest-opentelemetry needs Python 3.11 or later, pytest 8.0.0 or later, and version
1.28.0 or later of the OpenTelemetry API and SDK.
Installing a library that exposes a specific pytest-related entry point is automatically loaded as a pytest plugin. Simply installing the plugin should be enough to register it for pytest.
Using the --export-traces flag enables trace exporting (otherwise, the created spans
will only be tracked in memory):
pytest --export-traces
By default, this exports traces to http://localhost:4317, which will work well if
you're running a local OpenTelemetry
Collector exposing the OTLP gRPC interface.
You can use any of the OpenTelemetry environment
variables
to adjust the tracing export or behavior:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://another.collector:4317
pytest --export-traces
OTLP over gRPC is the default exporter, and the only one that pytest-opentelemetry
installs. To use another, install its package and name it in OTEL_TRACES_EXPORTER,
as you would for any OpenTelemetry SDK. For example, to export OTLP over HTTP:
pip install opentelemetry-exporter-otlp-proto-http
export OTEL_TRACES_EXPORTER=otlp_proto_http
export OTEL_EXPORTER_OTLP_ENDPOINT=http://another.collector:4318
pytest --export-traces
To describe where the tests ran, install the container extra. It adds
opentelemetry-container-distro,
and pytest-opentelemetry then records the process.* attributes of the pytest
process, and the Docker container and Kubernetes pod when it runs in one:
pip install 'pytest-opentelemetry[container]'
pytest-opentelemetry will use the name of the project's directory as the OpenTelemetry
service.name, but it will also respect the standard OTEL_SERVICE_NAME and
OTEL_RESOURCE_ATTRIBUTES environment variables. If you would like to permanently
specify those for your project, consider using the very helpful
pytest-env package to set these for all test
runs, for example, in your pyproject.toml:
[tool.pytest.ini_options]
env = [
"OTEL_RESOURCE_ATTRIBUTES=service.name=my-project",
]
If you are using the delightful pytest-xdist
package to spread your tests out over multiple processes or hosts,
pytest-opentelemetry will automatically unite them all under one trace. If this
pytest run is part of a larger trace, you can provide a --trace-parent argument to
nest this run under that parent:
pytest ... --trace-parent 00-1234567890abcdef1234567890abcdef-fedcba0987654321-01
The spans of a test run
A test run is one trace. Its root is a span named test run, and its children are a
collection span, a span for each test, and the spans of the fixtures that tests share:
test run
├─ collection
├─ database setup a fixture that tests share
├─ tests/test_api.py::test_health
│ ├─ tests/test_api.py::test_health::setup
│ │ └─ client setup a fixture of this test
│ ├─ tests/test_api.py::test_health::call
│ └─ tests/test_api.py::test_health::teardown
│ └─ client teardown
└─ database teardown
Each fixture has a <name> setup span and a <name> teardown span. The spans that your
code creates while a fixture sets up or tears down are children of those spans.
The spans of a fixture that pytest sets up for one test are inside that test. The spans of a fixture that tests share are children of the test run. pytest sets up a shared fixture during the first test that uses it, and tears it down during the last, but neither test's span includes that time: a test's span starts after pytest has set up those fixtures, and ends when pytest has torn down the test itself, before it tears them down. The duration of a test is then the time of the test and of its own fixtures, wherever the test falls in its module.
What a fixture's scope says and what pytest does can differ. pytest sets up a class-scoped fixture for every test that is not in a class, and it sets up a fixture for every test that parametrizes it along with a plain argument. The spans of those fixtures are inside each test.
A fixture whose setup raises records the exception on its setup span, and on the span of
the test that asked for it. An error in a fixture's teardown is recorded on the
::teardown span of the test that pytest reports it for, which for a shared fixture is
the last test that used it. That test's own span keeps the status of its call.
Some things do not follow that layout:
- A shared fixture that pytest sets up after one of the test's own fixtures sets up in
the middle of that test. Its setup span is inside the test, and its time counts
toward the test's duration. This happens to a fixture that a test first asks for with
request.getfixturevalue(), and to a fixture that another fixture of the same name overrides and depends on. - A finalizer that is added to a fixture after the fixture has set up, like the one a factory fixture adds each time a test calls it, runs before that fixture's teardown span starts. For a shared fixture it runs as a child of the test run, outside of any test.
- The spans that a
pytest_runtest_setuporpytest_runtest_logstarthook creates are children of the test run. The test's span covers their time, but it does not exist yet when pytest calls those hooks. - With
pytest-asyncio, the spans that an async fixture creates while it tears down are children of its setup span, because the fixture resumes in the context it set up in.
With --trace-per-test there is no test run span. Each test is the root of a trace
of its own, and so is everything that is a child of the test run above: each setup and
each teardown of a shared fixture, and each span from one of those hooks. When there
is a --trace-parent, they are children of that parent instead.
Parametrized tests
The tests that pytest makes from one parametrized function share a span name, which is
the node ID without the ID of the parameters, like tests/test_api.py::test_login. A
tool that groups spans by name then reports them together. The pytest.nodeid
attribute of each span has the whole node ID, like
tests/test_api.py::test_login[bearer].
The spans of a parametrized test have each of its parameters as an attribute named
pytest.param.<name>, from @pytest.mark.parametrize, a fixture's params, or a
tavern test's parametrize mark. A string, a
boolean, or a number keeps its value, and any other value becomes its repr(). A value
longer than 120 characters keeps its start and its end, with … in place of the middle.
The setup and teardown spans of a fixture with a parameter have the same name for every
parameter, and have the parameter as pytest.param.<name of the fixture>.
Working with other plugins
pytest-opentelemetry registers the object that creates its spans under the name
opentelemetry. Another plugin or a conftest.py can get it from pytest's plugin
manager, for example to read the span for the whole test run:
def pytest_collection_finish(session):
plugin = session.config.pluginmanager.get_plugin("opentelemetry")
trace_id = plugin.session_span.get_span_context().trace_id
With --trace-per-test there is no span for the whole run, so session_span is not
set.
Tests that freeze time
If freezegun is installed,
pytest-opentelemetry adds opentelemetry and pytest_opentelemetry to freezegun's
list of ignored packages. Spans then start and end at the real time, even while a test
has time frozen, so their durations stay correct. This covers every span that
OpenTelemetry records during the test run, including the ones your application creates.
Visualizing test traces
One quick way to visualize test traces would be to use an OpenTelemetry Collector feeding traces to Jaeger. This can be configured with a minimal Docker Compose file like:
version: "3.8"
services:
jaeger:
image: jaegertracing/all-in-one:1.33
ports:
- 16686:16686 # frontend
- 14250:14250 # model.proto
collector:
image: otel/opentelemetry-collector-contrib:0.49.0
depends_on:
- jaeger
ports:
- 4317:4317 # OTLP (gRPC)
volumes:
- ./otelcol-config.yaml:/etc/otelcol-contrib/config.yaml:ro
With this otelcol-config.yaml:
receivers:
otlp:
protocols:
grpc:
processors:
batch:
exporters:
jaeger:
endpoint: jaeger:14250
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [jaeger]
Developing
Two references I keep returning to is the pytest guide on writing plugins, and the pytest API reference:
- https://docs.pytest.org/en/stable/how-to/writing_plugins.html
- https://docs.pytest.org/en/stable/reference/reference.html#hooks
These are extremely helpful in understanding the lifecycle of a pytest run.
To get set up for development, install uv, then install this package and its development tools into a virtual environment, and install the git hooks:
uv sync
uv run prek install
Run the tests and the checks with:
uv run pytest
uv run prek run --all-files
hatch-vcs gets the version from the git tags, so pull requests do not
change a version anywhere.
Metadata
Release files for pytest-opentelemetry 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pytest_opentelemetry-2.0.0.tar.gz | 84.9 kB | With provenance | Details for pytest_opentelemetry-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pytest_opentelemetry-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for pytest_opentelemetry-2.0.0-py3-none-any.whl |
Total release size: 104.5 kB
Release files / pytest_opentelemetry-2.0.0.tar.gz
| Download URL | pytest_opentelemetry-2.0.0.tar.gz |
|---|---|
| Size | 84.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7b982d20cdce0c16be5481a9234bc36915fc535a17018adb83617d997242c396
|
|
BLAKE2b-256 checksum How to use checksums |
75a0c85dd392005130a3a10a3f0dd1bc6622fcb54463052bc4c7e5059b43bbc7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / pytest_opentelemetry-2.0.0-py3-none-any.whl
| Download URL | pytest_opentelemetry-2.0.0-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
96e176ce3f9d6638415ad5edfa4e5eef917bd7c75b30aefdecf442fa8ac45bac
|
|
BLAKE2b-256 checksum How to use checksums |
ce1ca3b35df46ccc765c3ca3e72421ce0e4b39babf5fec2bcf4064d29fb74770
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for pytest-opentelemetry 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pytest_opentelemetry-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.