The Locust Web UI is more than just a dashboard; it’s a dynamic command center where you can spin up and tear down load test scenarios, observe performance metrics in real-time, and even adjust test parameters on the fly, all from your browser.
Let’s see it in action. Imagine you have a simple Locustfile like this:
from locust import HttpUser, task, between
class WebsiteUser(HttpUser):
wait_time = between(1, 5)
host = "http://localhost:8080" # Target your application here
@task
def index(self):
self.client.get("/")
@task
def about(self):
self.client.get("/about/")
When you run Locust with locust -f your_locustfile.py, you’ll navigate to http://localhost:8089 (by default) and see a clean interface.
The initial screen prompts you for two crucial pieces of information:
- Number of users: The total number of concurrent users you want to simulate.
- Spawn rate: How many new users should be started per second.
Let’s say you input 100 for users and 10 for spawn rate. Upon clicking "Start swarming," the UI transforms. You’ll see a "Running" status, and the graphs begin to populate.
The core of the UI is its real-time monitoring. You’ll see:
- Total requests: The cumulative number of requests sent.
- Failures: The count of requests that returned an error status code (e.g., 5xx, 4xx).
- Medians/95th percentiles: How quickly requests are being served, giving you a sense of typical and worst-case response times.
- Current users: The number of simulated users currently active.
- Current requests: The number of requests currently in flight.
- RPS (Requests per Second): The throughput of your application under test.
This data is crucial for understanding how your application behaves under stress. You can observe spikes in response times or failures as user load increases, pinpointing potential bottlenecks.
But the UI isn’t just for passive observation. You have control. The "Stop" button, prominently displayed, allows you to halt the test immediately. More interestingly, you can adjust the swarm. If you see response times creeping up and want to see if a slightly lower user count helps, you can input a new "Number of users" and click "Adjust swarm." Locust will gracefully scale down the user count. Similarly, you can increase the user count or change the spawn rate mid-test. This dynamic adjustment capability is invaluable for interactive performance tuning.
You can also select which tasks your simulated users will execute. If your Locustfile defines multiple @task decorated methods, you can choose to run only specific ones, allowing you to isolate the performance impact of particular features.
The "Statistics" tab breaks down performance by endpoint (e.g., /, /about/). For each endpoint, you get detailed metrics: number of requests, failures, average response time, median, 95th percentile, and min/max response times. This granular view helps you identify which specific API calls or page loads are causing issues.
The "Failures" tab lists each failed request, showing the URL, the method (GET, POST, etc.), the status code, and the response content, which is extremely helpful for debugging.
The "Download data" button allows you to export all the collected statistics as a CSV file for deeper offline analysis.
The real power of the UI lies in its ability to provide immediate feedback on changes. Deploy a new version of your application, start a test, and within seconds, you can see if the new version is faster, slower, or more error-prone. You can then stop the test, revert the deployment, and test again. This rapid feedback loop accelerates the development and optimization process significantly.
One subtle but powerful aspect of the Web UI is its handling of distributed testing. When you run Locust in distributed mode (one master, multiple workers), the Web UI, running on the master node, aggregates statistics from all workers. This means you get a unified view of your entire load test, even if it’s spread across many machines, without needing to manually combine logs or metrics. You simply start the master with locust -f your_locustfile.py --master and workers with locust -f your_locustfile.py --worker --master-host=<master_ip>. The UI then shows the combined load.
The next step after mastering the UI for basic monitoring is understanding how to integrate custom metrics into it.