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

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.0
File Size Uploaded Provenance Actions
pytest_opentelemetry-1.2.0.tar.gz 74.9 kB Without provenance Details for pytest_opentelemetry-1.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 88.2 kB

Release files / pytest_opentelemetry-1.2.0.tar.gz

Download URL pytest_opentelemetry-1.2.0.tar.gz
Size 74.9 kB
Tags Source
SHA-256 checksum
How to use checksums
8577a6180c5ba1f855c487f933c7973a40c4bbe9511441fae7e5ec0d4a0e99f3
BLAKE2b-256 checksum
How to use checksums
d0ee6e3c4625d5ce48930f34bceea8d28bb4b171ef1f61d72a76896c6cb4ce91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL pytest_opentelemetry-1.2.0-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c5c0bdf900620fba1e93cf692b131639908318248bca11a7cecd2a718fa1c0d
BLAKE2b-256 checksum
How to use checksums
5aeff696dec29c60c66af0206102e4ae8c53d097a999273fb6f1a47a290edfc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for pytest-opentelemetry 1.2.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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