Skip to main content

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

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

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 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:

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 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-opentelemetry 1.2.1
File Size Uploaded Provenance Actions
pytest_opentelemetry-1.2.1.tar.gz 75.0 kB With provenance Details for pytest_opentelemetry-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-opentelemetry 1.2.1
File Interpreter ABI Platform Actions
pytest_opentelemetry-1.2.1-py3-none-any.whl Python 3 none any Details for pytest_opentelemetry-1.2.1-py3-none-any.whl

Total release size: 88.2 kB

Release files / pytest_opentelemetry-1.2.1.tar.gz

Download URL pytest_opentelemetry-1.2.1.tar.gz
Size 75.0 kB
Tags Source
SHA-256 checksum
How to use checksums
6a3f53a048c13735fef6f19fdf1fd6634bdc70986ed50efc0f9d7778f6ab1354
BLAKE2b-256 checksum
How to use checksums
d9d339cec9048aba27dc817ff37dc106a2d6c4915d43168f65f032806ff92822
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 19, 2026.

Transparency log

Release files / pytest_opentelemetry-1.2.1-py3-none-any.whl

Download URL pytest_opentelemetry-1.2.1-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
49c5fcd800f6b92e88af69bf78e649b23e002e2f91a658f28116ba118e0625bd
BLAKE2b-256 checksum
How to use checksums
6deecdf4e344152ebd4d22a45b5b616a58537cb60700058697bb3a6261383b70
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 19, 2026.

Transparency log

Security for pytest-opentelemetry 1.2.1

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.

Select from 2 files

Attestation for pytest_opentelemetry-1.2.1.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 19, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page