Back to all tools
cloudstorm
Load test from many AWS regions with one command line.
cloudstorm is a free, open-source CLI (MIT license, Python 3.10+) for distributed load testing. It launches EC2 instances in the regions you choose, installs the load testing tool you pick (Locust, k6, JMeter or Artillery) on them through AWS Systems Manager, so no SSH keys are needed, starts the test on every instance, merges the results into one JSON, CSV or HTML report, and removes the resources it created. Only test systems you own or have written authorization to test.
Features
Distributed
- EC2 instances in the regions you choose, one command to create them
- Locust (Python), k6 (Go), JMeter (Java) or Artillery (Node.js) with the same workflow
- The total number of users is divided across all instances
- Commands run through AWS Systems Manager: no SSH keys
Results
- Results of all instances and regions merged into one report (JSON, CSV or HTML)
- Thresholds on p90, p95, p99, avg, median, min, max, error_rate, rps and total_requests (merged percentiles are weighted averages, an approximation)
- Exit code 1 when a threshold is breached or nothing ran
- Your own test script with --script (one example per tool in the repository)
Cost and Cleanup
- Estimated hourly cost printed before instances are created
- Warning when users per instance exceed a memory-based limit for the tool and instance type
- cleanup terminates the instances and deletes the security groups and VPCs cloudstorm created
- cleanup --all also deletes the IAM role and instance profile
Installation & Usage
Install (Python 3.10 or later)
pip install cloudstorm cloudstorm --version
Docker (amd64 and arm64)
docker run --rm \ -v ~/.aws:/home/cloudstorm/.aws:ro \ -v ~/.cloudstorm:/home/cloudstorm/.cloudstorm \ -v "$PWD":/work \ tarekcheikh/cloudstorm auth -p my-profile
A Complete Test
cloudstorm auth -p my-profile # check credentials cloudstorm create -p my-profile -r us-east-1,eu-west-1,ap-northeast-1 -n 2 --tool locust cloudstorm run https://example.com -p my-profile -u 1000 -s 50 -d 5m -o results.json cloudstorm report results.json -f html -o report.html cloudstorm cleanup --all -p my-profile -y # remove what cloudstorm created
Pass/Fail Thresholds for CI
cloudstorm run https://staging.example.com --tool k6 -u 10000 -d 60s \ --threshold "p95 < 500" \ --threshold "error_rate < 1" \ -y
CLI Options
| Option | Description |
|---|---|
auth | Check AWS credentials and permissions |
create -r REGIONS -n N -t TYPE --tool TOOL | Create the instances (default instance type: t3.medium) |
add | Add instances to existing infrastructure |
run TARGET_URL -u -s -d -e -o | Run a load test: users, spawn rate, duration, endpoints, JSON output file |
run --script PATH | Use your own test script instead of the default GET requests |
run --threshold "p95 < 500" | Pass/fail threshold, repeatable |
status | Show existing cloudstorm infrastructure |
cleanup -r REGIONS | --all | Terminate instances and delete the resources cloudstorm created |
report INPUT_FILE -f [json|csv|html] -o FILE | Generate a report from a results file |
tools | List the available tools |
Need Help Implementing?
We can help you deploy and customize this tool for your specific needs, or build custom solutions.
Contact Us