Performance Testing Sample Project with Locust, Grafana, and Prometheus

This is a complete sample project that helps you quickly set up an environment for performance testing. The project uses Locust to generate load, a demo web application written in Python Flask as the test target, Prometheus to collect metrics, and Grafana to visualize the results.

The entire system is containerized using Docker and managed by Docker Compose, making installation and execution incredibly simple.

System Architecture

1. Locust: Simulates users to generate HTTP requests to the demo web application.
2. Go App: A simple web application to receive requests from Locust. This app also exposes metrics (e.g., request count, response time) for Prometheus to collect.
3. Prometheus: A time-series database that periodically scrapes metrics data from Locust and the Flask App.
4. Grafana: Queries data from Prometheus and displays it in beautiful, easy-to-understand charts and dashboards, allowing for real-time monitoring of test results.

Key Features

• Easy Setup: A single docker-compose up command launches the entire system.
• Ready Integration: Everything is pre-configured to work together seamlessly.
• Sample Dashboard: A sample Grafana dashboard is provided so you can view results immediately.
• Flexible Customization: Easily replace the demo app with your own application or customize the test script in locustfile.py.

System Requirements

• Docker
• Docker Compose

Installation and Usage Guide

1. Clone the repository

git clone https://github.com/vkhangstack/Locust-Sample.git
cd Locust-Sample

2. Launch the system

Use Docker Compose to build and run all services (Locust, Grafana, Prometheus, Demo App).

docker-compose up --build -d

After the command finishes, you can access the services at the following ports:

• Demo Web App: http://localhost:8080
• Locust Web UI: http://localhost:8089
• Grafana: http://localhost:3000 (Default credentials: admin/admin)
• Prometheus: http://localhost:9090

3. Start the Performance Test

• Access the Locust web interface: http://localhost:8089.
• In the "Number of users" field, enter the number of concurrent users you want to simulate.
• In the "Spawn rate" field, enter the number of users to spawn per second.
• In the "Host" field, enter the address of the demo web application. Since the containers are running in the same Docker network, you need to use the service name defined in docker-compose.yml.
  • Host: http://app:8080
• Click "Start swarming" to begin generating load.

4. View results on Grafana

• Access Grafana at http://localhost:3000 and log in (default is admin/admin).
• On your first login, Grafana may ask you to change your password.
• The system is pre-configured to automatically add Prometheus as a Data Source and import a sample Dashboard.
• Go to the Dashboards section, find and open the dashboard named "Locust Stats" or similar.
• You can now see real-time charts for requests per second, response times, failure counts, and more.

Directory Structure

The project structure is as follows:

.
├── main.go               # The demo Go web application
├── locustfile.py               # Contains the Locust test script
├── grafana/
│   └── provisioning/     # Auto-configuration for Grafana
│       ├── dashboards/
│       │   └── dashboard.yml
│       └── datasources/
│           └── datasource.yml
├── prometheus/
│   └── prometheus.yml    # Configuration for Prometheus
└── docker-compose.yml    # Defines and links the services

Customization

• Change the test script: Modify the locustfile.py file to change the endpoints to be tested or the test logic.
• Test your own application: Edit the docker-compose.yml file to point to your application's image instead of the demo app. Don't forget to update prometheus/prometheus.yml if your metrics endpoint is different.

License

This project is licensed under the MIT License - Copyright (c) 2025 Pham Van Khang.

Happy testing!