locust-telemetry 2.0.1

A Locust plugin to log load test metrics to observability tools (DB-free).

Locust Telemetry

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

---

Why Locust Telemetry?

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.

---

Key Features

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

---

Installation

pip install locust-telemetry

---

Quick Start

1. Initialize the plugin

In your locustfile.py:

from locust_telemetry import entrypoint

entrypoint.initialize()

2. Run Locust with telemetry enabled

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.

---

Local Demo (Docker)

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/latest/examples.html

---

Dashboard Preview

JSON Telemetry (Loki / Grafana Logs)

OpenTelemetry Metrics (Prometheus / Grafana)

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

Author

Swaroop Shubhakrishna Bhat (@ss-bhat)

Thanks to all contributors ❤️

---

License

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