Scaling Gatling Tests with Distributed Execution: A Practical Guide

Desired Outcome

Run a single Gatling scenario on multiple machines, aggregate metrics in real‑time, and generate a single consolidated HTML report that reflects the combined load. The goal is to verify that the target system can sustain a higher aggregate traffic volume than a single‑node test would reveal.

Prerequisites

• Gatling 4.x (or 3.x with manual JVM settings) installed on every node or a Docker image that includes Gatling.
• Network connectivity between all nodes: the master must reach each worker on port 8090, and workers must expose port 8091 for reporting.
• Firewall rules allowing TCP traffic on 8090–8091.
• Basic knowledge of Docker Compose if using the template.
• Same version of Gatling on master and workers to avoid compatibility issues.

Configuring the Cluster

1. Prepare the Docker‑Compose Template

The Gatling team ships a ready‑made docker-compose.yml that provisions one master and two workers. Copy it to a working directory and adjust the hostnames or IPs if necessary.

# docker-compose.yml
version: "3.8"
services:
  gatling-master:
    image: gatling/gatling:latest
    container_name: gatling-master
    environment:
      - GATLING_DISTRIBUTED_MASTER=true
      - GATLING_DISTRIBUTED_MASTER_HOST=gatling-master
    ports:
      - "8090:8090"   # REST API
      - "8091:8091"   # Report port
    volumes:
      - ./scenarios:/opt/gatling/conf

  gatling-worker-1:
    image: gatling/gatling:latest
    container_name: gatling-worker-1
    environment:
      - GATLING_DISTRIBUTED_WORKER=true
      - GATLING_DISTRIBUTED_MASTER_HOST=gatling-master
    depends_on:
      - gatling-master
    volumes:
      - ./scenarios:/opt/gatling/conf

  gatling-worker-2:
    image: gatling/gatling:latest
    container_name: gatling-worker-2
    environment:
      - GATLING_DISTRIBUTED_WORKER=true
      - GATLING_DISTRIBUTED_MASTER_HOST=gatling-master
    depends_on:
      - gatling-master
    volumes:
      - ./scenarios:/opt/gatling/conf

Place your scenario files in a scenarios directory that is mounted into each container. The environment variables tell the master to listen on its ports and each worker to register with the master’s hostname.

2. Start the Cluster

Run the following command from the directory containing docker-compose.yml:

docker compose up -d

Use -d to detach. Verify that all containers are running:

docker compose ps

Check the master’s health endpoint to ensure workers are registered:

curl http://gatling-master:8090/api/health

Expected output (simplified):

{"status":"OK","workers":["gatling-worker-1","gatling-worker-2"]}

Running a Distributed Test

With the cluster up, launch the scenario from the master node. You can do this either inside the master container or from a host machine that can access the master’s ports. The command below runs the test named MyScenario with 100 virtual users (VUs) per worker.

docker compose exec gatling-master gatling.sh -s MyScenario -r 100

Parameters:

• -s – scenario name (matching the Scala class).
• -r – number of VUs per worker.

During execution, the master’s REST API streams status updates. Poll the endpoint to view progress:

curl http://gatling-master:8090/api/status

Typical JSON output will include currentUsers and completedUsers fields.

Monitoring Progress

Gatling exposes an HTTP endpoint on the master that returns real‑time metrics. Use a browser or curl to open http://gatling-master:8090/api/status. The response contains:

Field	Description
workers	List of registered workers
currentUsers	Active users across all workers
completedUsers	Users that finished the scenario
errorCount	Number of failed requests

Set a short polling interval (e.g., every 10 seconds) to watch the load ramp‑up and to detect anomalies early.

Validating Aggregated Results

After all workers finish, Gatling writes a single HTML report to the master’s /opt/gatling/results directory. The report includes a scenarios section that lists each worker’s contribution. Open index.html in a browser to verify:

• All workers appear in the Scenarios table.
• Metrics such as Requests per second and Response time percentiles reflect the combined load.
• The report timestamp matches the test start time.

To programmatically confirm inclusion, you can grep the report for the worker names:

grep -R "gatling-worker" /opt/gatling/results/index.html

Any missing worker indicates a reporting failure.

Recovery and Troubleshooting

Worker Orphaned

If a worker fails to register, the master’s health endpoint will omit it. Check the worker logs:

docker compose logs gatling-worker-1

Common causes: network partition, wrong GATLING_DISTRIBUTED_MASTER_HOST, or the master’s port being blocked by a firewall. Resolve by ensuring DNS resolution or using the master’s IP address.

Master Failure

Should the master node crash mid‑test, workers will stall. Restart the master and re‑register workers:

docker compose restart gatling-master

After restart, re‑run the test from the new master instance. Note that any data collected before the crash is lost; consider checkpointing or using a persistent volume for /opt/gatling/results if you need to preserve partial data.

Network Issues

Verify connectivity with ping and telnet to ports 8090 and 8091. If a firewall blocks traffic, open the ports or place the nodes in the same security group.

Version Mismatch

All nodes must run the same Gatling version. Mixing 3.x and 4.x can cause serialization errors. Confirm the version inside each container:

docker compose exec gatling-master gatling.sh --version

Adjust the image tag in docker-compose.yml to match.

Limitations

• Aggregated reports are generated only after all workers finish; partial real‑time dashboards are not supported.
• Scaling beyond a handful of workers may require tuning JVM options (-Xms, -Xmx) to prevent out‑of‑memory errors.
• Network latency between workers and master can introduce skew in timing metrics.

Practical Check‑list

1. Validate baseline single‑node test.
2. Deploy Docker‑compose cluster.
3. Confirm all workers registered via /api/health.
4. Run distributed test and monitor /api/status.
5. After completion, inspect index.html for all workers.
6. Verify no orphaned workers in logs.
7. Document any network adjustments for future runs.

Following this guide ensures a reproducible, scalable Gatling test harness that aggregates performance data across multiple nodes.