OpenTelemetry Integration

Locust now optionally integrates with OpenTelemetry (OTel), enabling you to automatically export traces and metrics from your load tests to any OTel-compatible backend (OTLP, Prometheus, Jaeger, Tempo, etc.). This makes it easy to correlate load-test activity with application and infrastructure telemetry in your observability stack.

The configuration is done via environment variables. See the OpenTelemetry documentation for details on how to configure exporters, resource attributes, sampling, etc.

Setup

To enable OpenTelemetry, you need to download locust with the OpenTelemetry dependencies:

$ pip install locust[otel]

Then, pass the command line argument --otel to enable OpenTelemetry:

$ locust --otel
...

If you’re using Docker, the locustio/locust-otel image has the OpenTelemetry dependencies pre-installed. See Running in Docker for details.

Exporters

Locust supports the following OpenTelemetry exporters, for both traces and metrics, out of the box:

  • OTLP (gRPC and HTTP) - this is the default exporter using gRPC protocol

  • Console (useful for debugging)

For traces, BatchSpanProcessor is used and can be configured with these variables.

For metrics, PeriodicExportingMetricReader is used and is configurable with the corresponding variables.

Auto Instrumentation

Note

Currently, only the requests library is auto-instrumented. This mean that only HttpUser will have it’s HTTP requests made during your load tests automatically generate spans, and metrics with no additional configuration needed.

We plan to add auto-instrumentation for more libraries in future releases.

Supported Users

User Class

Instrumented Library

HttpUser

requests

If you need instrumentation for other libraries (e.g., database clients, messaging libraries), you can manually set up additional instrumentation using the OpenTelemetry Python SDK as per the OpenTelemetry Python documentation.

Example

$ export OTEL_TRACES_EXPORTER=otlp
$ export OTEL_EXPORTER_OTLP_ENDPOINT=https://...
$ export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$ locust --otel
[2025-11-28 16:27:01,916] locust/INFO/locust.main: Starting Locust, OpenTelemetry enabled
[2025-11-28 16:27:01,916] locust/INFO/locust.main: Starting web interface at http://0.0.0.0:8089, press enter to open your default browser.
...