Locust Prometheus Exporter: Scrape Test Metrics (2026)

The Locust Prometheus Exporter doesn’t actually scrape metrics in the way a typical Prometheus exporter does; it’s more of a publisher that pushes metrics to Locust’s internal state, which Prometheus then scrapes.

Here’s how you can set up and use the Locust Prometheus Exporter to get your test metrics into Prometheus:

Setting Up the Exporter

First, you need to install the exporter. It’s usually installed as a Python package:

pip install locust-prometheus-exporter

Next, you’ll integrate it into your Locustfile. You’ll import the PrometheusExporter and initialize it.

from locust import HttpUser, task, between
from locust_prometheus_exporter import PrometheusExporter

# Initialize the exporter
exporter = PrometheusExporter("0.0.0.0", 9091) # Host and port for the exporter

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)
    host = "http://localhost:8000" # Replace with your target host

    # This task will report metrics to the exporter
    @task
    def index(self):
        self.client.get("/")

    # You can also define custom metrics
    @task
    def about(self):
        self.client.get("/about/")

    # Register custom metrics with the exporter
    def on_start(self):
        exporter.start(self) # Start the exporter when the user starts

    def on_stop(self):
        exporter.stop() # Stop the exporter when the user stops

When you run Locust, the exporter will start a web server on the specified host and port (e.g., 0.0.0.0:9091). This server exposes a /metrics endpoint that Prometheus can scrape.

Prometheus Configuration

Now, you need to configure Prometheus to scrape the metrics from the Locust exporter. In your prometheus.yml configuration file, add a scrape job:

scrape_configs:
  - job_name: 'locust'
    static_configs:
      - targets: ['localhost:9091'] # The host and port of your Locust exporter

After updating prometheus.yml, restart your Prometheus server. You should then see the Locust job appear in Prometheus’s "Targets" page, and it should show as "UP".

What Metrics You Get

The exporter automatically collects and exposes several key metrics about your Locust test:

• locust_users_total: Total number of users spawned.
• locust_users_running: Number of users currently running.
• locust_users_waiting: Number of users currently waiting.
• locust_requests_total: Total number of HTTP requests made. This is a counter and will have labels for method, name, status, and exception.
• locust_request_length_bytes_total: Total bytes transferred for requests.
• locust_response_length_bytes_total: Total bytes transferred for responses.
• locust_request_duration_seconds: A histogram of request durations. This is crucial for understanding response times.

You can query these metrics in Prometheus. For example, to see the total number of successful GET requests:

sum(rate(locust_requests_total{method="GET", status="200"}[5m]))

To see the 95th percentile response time for a specific endpoint:

histogram_quantile(0.95, sum(rate(locust_request_duration_seconds_bucket{name="/about/"}[5m])) by (le, name))

Custom Metrics

You can also define and expose your own custom metrics. These are useful for tracking application-specific KPIs during your load test.

from locust import HttpUser, task, between
from locust_prometheus_exporter import PrometheusExporter, Gauge, Counter

exporter = PrometheusExporter("0.0.0.0", 9091)

# Define custom metrics
custom_gauge = Gauge("my_custom_gauge", "A simple gauge metric")
custom_counter = Counter("my_custom_counter", "A simple counter metric")

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)
    host = "http://localhost:8000"

    @task
    def index(self):
        self.client.get("/")
        # Update custom metrics
        custom_gauge.set(self.environment.runner.user_count) # Set gauge to current user count
        custom_counter.inc() # Increment the counter

    def on_start(self):
        exporter.start(self)

    def on_stop(self):
        exporter.stop()

In this example, custom_gauge will show the current number of users, and custom_counter will increment with each execution of the index task. You would then query these using their defined names (e.g., my_custom_gauge, my_custom_counter).

The "Push" vs. "Scrape" Nuance

The terminology can be a bit confusing. While Prometheus is fundamentally a pull-based system (it scrapes targets), the Locust Prometheus Exporter acts as an intermediary. Locust itself is running the load test and accumulating metrics. The exporter then exposes these accumulated metrics via an HTTP endpoint that Prometheus scrapes. So, it’s not that Locust is pushing metrics to Prometheus directly, but rather the exporter is making Locust’s internal metrics available for Prometheus to pull.

The exporter essentially bridges Locust’s internal state with Prometheus’s scraping mechanism, allowing you to integrate load test performance data into your broader monitoring infrastructure.

The next thing you’ll likely want to do is build dashboards in Grafana using these scraped metrics to visualize your load test results alongside your application’s operational metrics.