Chapter 10 · Distributed Load Testing

Chapter goals: Master Locust's master/worker distributed architecture, learn to launch large-scale concurrency across multiple machines.

10.1 Why Distributed Testing Is Needed

A single machine's CPU, memory, and network bandwidth are finite. When simulating tens or hundreds of thousands of virtual users, a single-process Locust cannot generate enough throughput. Locust's distributed mode solves this with one master node + multiple worker nodes:

┌──────────┐     ┌──────────┐
│  Master  │────▶│ Worker 1 │──▶ Target System
│ (Stats)  │     └──────────┘
│          │     ┌──────────┐
│          │────▶│ Worker 2 │──▶ Target System
└──────────┘     └──────────┘

The Master produces no requests — it only distributes user counts and task definitions to workers, then aggregates all stats. Each worker is an独立 Python process running the same locustfile.

10.2 Starting the Master

locust -f locustfile.py --master --host https://api.example.com
# Defaults: Web UI on port 8089
# Worker communication ports: 5557 (TCP) and 5558 (UDP)

Key parameters:

Parameter	Description
--master	Start in master mode
--master-bind-host	Listen address (default *)
--master-bind-port	Communication port (default 5557)
--expect-workers	Wait for N workers to connect before starting

Use --expect-workers to prevent the master from starting before all workers connect:

locust -f locustfile.py --master --expect-workers 4

10.3 Starting Workers

On each load-testing machine:

locust -f locustfile.py --worker --master-host=192.168.1.100
# --worker declares this node as a worker
# --master-host points to the master's IP (default: localhost)

Same locustfile

All workers must access the same version of locustfile.py as the master. Recommended approaches:

• Place the locustfile in a shared filesystem or git repo;
• Or use a Docker image to distribute uniformly.

10.4 Capacity Planning

How many concurrent users each worker can simulate depends on hardware and script complexity. Rule of thumb:

• Simple HTTP GET: ~2,000–5,000 concurrent users per worker;
• Complex POST + JSON parsing: ~500–1,500 concurrent users;
• CPU-intensive assertions or encryption: even lower.

Estimate required workers:

workers_needed = target_users / per_worker_capacity

# Example: target 50,000 users, 2,500 per worker
workers_needed = 50_000 / 2_500  # = 20 worker machines

10.5 Docker Compose Orchestration

# docker-compose.yml
version: "3"
services:
  master:
    image: locustio/locust
    ports:
      - "8089:8089"
    volumes:
      - ./:/mnt/locust
    command: -f /mnt/locust/locustfile.py --master -H http://master:8089

  worker:
    image: locustio/locust
    volumes:
      - ./:/mnt/locust
    command: -f /mnt/locust/locustfile.py --worker --master-host master

Start master + 4 workers:

docker compose up -d master
docker compose up -d --scale worker=4

10.6 Chapter Summary

• Master node: schedules and aggregates; produces no traffic;
• Worker nodes: each runs the same locustfile independently;
• --expect-workers prevents premature test starts;
• Capacity planning: estimate users-per-worker, then scale machines accordingly.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the role of the Master node in Locust distributed mode?

2. What does --expect-workers 4 do?

3. How many workers do you need for 100,000 concurrent users if each worker handles 2,500?

4. Why must all workers run the same locustfile version?

🛠️ Hands-On Exercises

1. Set up a master + 2-worker Docker Compose stack; run a headless test and verify all 3 nodes appear in the Master's Web UI.
2. Calculate how many workers you need to hit 200,000 concurrent users given your local machine's per-worker capacity (run a small test to measure).
3. Simulate a worker failure by killing one worker mid-test; observe how the Master's stats change.

Proceed to Chapter 11: Docker Containerized Running.