Articles

Locust + Grafana: Real-Time Load Test Dashboards (2026)

April 18, 2026 4 min read

Grafana makes load testing feel like air traffic control for your application, not just a black box that spits out pass/fail results.

Let’s watch Locust and Grafana dance. Imagine you’ve got a Locustfile that simulates users hitting your web app:

from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)

    @task
    def index(self):
        self.client.get("/")

    @task
    def about(self):
        self.client.get("/about/")

When you run Locust, it starts spitting out metrics like requests per second, response times, and failure rates. But looking at a terminal stream of numbers? That’s like reading a flight manifest instead of watching the planes.

This is where Grafana steps in. It’s a dashboarding tool that can pull data from various sources, including Locust. The magic happens because Locust can expose its real-time metrics in a format Grafana understands.

Here’s how to get them talking:

  1. Locust Exports Metrics: Locust has a built-in capability to export its metrics over HTTP. By default, it exposes them at the /stats/report endpoint. This isn’t directly what Grafana needs, but it’s the source.

  2. StatsD/Prometheus Exporter: The most common way to get Locust metrics into Grafana is by using an intermediary that translates Locust’s output into a format Grafana can query.

    • StatsD: Locust can be configured to send metrics to a StatsD server. StatsD is a simple daemon that aggregates metrics and forwards them to other backends.
    • Prometheus: A more modern and powerful approach is to use Locust’s Prometheus exporter. This involves running Locust with a specific flag that exposes metrics in Prometheus exposition format. Grafana natively supports Prometheus as a data source.

Let’s focus on the Prometheus approach as it’s more direct for Grafana integration.

Setting up Prometheus Exporter with Locust:

When you start Locust, use the --metrics-exporter-port argument. This tells Locust to start an HTTP server that exposes Prometheus-formatted metrics.

locust -f your_locust_file.py --metrics-exporter-port 9091

This command starts Locust and also a Prometheus metrics endpoint on http://localhost:9091/metrics. You can visit this URL in your browser to see the raw metrics being generated.

Setting up Grafana:

  1. Install Grafana: If you don’t have it, install Grafana. The easiest way is often via Docker:

    docker run -d -p 3000:3000 grafana/grafana

    Access it at http://localhost:3000. Default login is admin/admin.

  2. Add Prometheus Data Source:

    • In Grafana, go to "Configuration" (gear icon) -> "Data sources".
    • Click "Add data source".
    • Select "Prometheus".
    • In the "URL" field, enter http://localhost:9091 (this is the address of your Locust metrics exporter).
    • Click "Save & Test". You should see a "Data source is working" message.

  3. Import a Pre-built Locust Dashboard: The Grafana community has created excellent dashboards for Locust. You can find them on the Grafana Dashboards website. Search for "Locust". A popular one is ID 8771 or similar ones focused on Locust performance.

    • Go to "Create" (plus icon) -> "Import".
    • Enter the dashboard ID (e.g., 8771) or upload a JSON file if you downloaded one.
    • Under "Options", select your Prometheus data source (the one you just configured).
    • Click "Import".

Now you have a live dashboard! You’ll see panels showing:

  • Requests per second (RPS): How many requests your application is handling.
  • Response Times: Average, median, and percentile (e.g., 95th, 99th) response times. This is crucial for understanding user experience.
  • Failures: The rate of failed requests, broken down by HTTP status code or exception.
  • User Count: The number of active users simulated by Locust.

The real-time nature means you can start your load test, watch the metrics climb, and immediately see how your application behaves under stress. You can correlate spikes in response time with increased user load or observe failures appearing as you push past capacity.

The Prometheus exporter for Locust provides a rich set of metrics. You’ll see metrics like locust_user_count, locust_requests_total (which is a counter, so you’ll use rate() in Grafana queries), locust_request_response_times_seconds (a histogram, for percentiles), and locust_failures_total.

When querying these in Grafana, you’ll often use PromQL. For example, to show requests per second:

rate(locust_requests_total{job="locust"}[1m])

And for the 95th percentile response time:

histogram_quantile(0.95, rate(locust_request_response_times_seconds_bucket{job="locust"}[1m]))

The job="locust" part is important if you have multiple Prometheus targets; it helps filter to your Locust instance. The rate(...[1m]) calculates the per-second average over the last minute, smoothing out fluctuations. histogram_quantile is the magic function for getting percentiles from Prometheus histograms.

The most surprising thing is how granular you can get with the response time data. Locust by default exposes response times as a Prometheus histogram. This isn’t just an average; it’s a distribution of latencies. Grafana’s histogram_quantile function can then compute any percentile (like 90th, 95th, 99th) on the fly, giving you a much clearer picture of user experience than a simple average ever could. You can see if a small but significant percentage of users are experiencing very long delays, even if the average looks good.

Once you’ve mastered real-time monitoring, the next step is to integrate alerting into Grafana based on these metrics.

Want structured learning?

Take the full Locust course →