Locust Telemetry is a modular observability plugin for the Locust load-testing framework.

It emits structured telemetry from load tests so you can correlate request behavior with system metrics using modern observability tools.

📖 Full documentation: https://locust-telemetry.readthedocs.io/en/stable/index.html

Load testing is most effective when request-level metrics can be correlated with system signals like CPU, memory, network usage, and errors.

Locust Telemetry bridges this gap by exporting structured telemetry that integrates cleanly with existing observability stacks.

• Structured Telemetry Test lifecycle events, request metrics, and system metrics

• Multiple Backends JSON logs or OpenTelemetry metrics

• OpenTelemetry Native OTLP export to Prometheus, Grafana, Datadog, New Relic, and more

• Distributed Support Works with Locust master–worker mode

• Extensible Design Add custom recorders and instruments

Traces and spans are planned but not yet supported.

pip install locust-telemetry

In your locustfile.py:

from locust_telemetry import entrypoint

entrypoint.initialize()

JSON telemetry (logs):

locust -f locustfile.py --testplan mytest --enable-telemetry-recorder json

OpenTelemetry metrics:

locust -f locustfile.py --testplan mytest --enable-telemetry-recorder otel

➡️ See the Configuration section in the docs for all available options.

A complete local observability stack is provided to quickly try both JSON and OpenTelemetry telemetry:

git clone https://github.com/platform-crew/locust-telemetry.git
cd locust-telemetry/examples/local
make build && make up

• Locust UI: http://localhost:8089
• Grafana: http://localhost:3000

📘 Full walkthrough: https://locust-telemetry.readthedocs.io/en/stable/examples.html

JSON Telemetry (Loki / Grafana Logs)

OpenTelemetry Metrics (Prometheus / Grafana)

Contributions are welcome! Please see contributing for guidelines.

Swaroop Shubhakrishna Bhat (@ss-bhat)

Thanks to all contributors ❤️

Licensed under the Apache License 2.0. See LICENSE for details.