plgm is a load generator and benchmark tool for sharded and non-sharded MongoDB clusters, written in Go. It tests your database with your own schema and your own queries instead of synthetic data, so the numbers you get reflect how your application will behave.
Use it to:
- Benchmark your own workload. Define your collections and queries, seed realistic data with every standard BSON type, and run find, insert, update, delete, aggregate, and transactional operations at the ratios you choose.
- Model real traffic. Ramp, step, spike, or oscillate the worker count, add client think time, and send most traffic to a hot set of documents.
- Find out why a query is slow. After the run, PLGM explains every query shape it executed and reports scan efficiency, in-memory sorts and disk spills, and index recommendations.
- Track changes between runs. Keep a history of runs, pin reference runs, and compare up to eight side by side.
- Compare runs and servers on the same charts. Put the throughput and latency of runs from different days, or of different servers, on top of each other, and watch a running workload draw against the finished ones.
- Repeat a run with the same settings. Every run's settings are saved automatically, and you load any of them by choosing it from a list.
- Test upgrades and migrations. Record a workload once, then replay the exact same operations on up to eight servers in one run and compare results and latency operation by operation. You can also replay traffic captured from your mongod logs.
It ships as a single binary with an embedded Web UI, uses all available CPUs by default (GOMAXPROCS), and is fully configurable through config.yaml, environment variables, or the browser.
The Compare Runs tab draws runs and servers on the same charts. The solid line is the workload that is running now; the dashed lines are finished runs. See Compare Runs.
2½-minute walkthrough: record a workload, replay it on three servers, compare them on the dashboard charts, and open the comparison report.
plgm_walkthrough.mp4
Option 1: Download a release
Go to the Releases page, download the .tar.gz file for your operating system, and extract it:
# Example for Linux
tar -xzvf plgm-linux-amd64.tar.gz
# Example for Mac (Apple Silicon)
tar -xzvf plgm-darwin-arm64.tar.gzOption 2: Build from source (requires Go 1.25+)
git clone https://github.com/Percona-Lab/percona-load-generator-mongodb.git
cd percona-load-generator-mongodb
go mod tidy
# Build a binary for your CURRENT machine only (no .tar.gz)
make build-local
# Run it
./bin/plgm --helpTo build release packages for Linux and Mac, run make build. It writes bin/plgm-linux-amd64.tar.gz, bin/plgm-darwin-amd64.tar.gz, and bin/plgm-darwin-arm64.tar.gz.
Download config.yaml and set your connection string. The built-in default workload runs without any other files. If you use the Web UI, you can set everything in the browser instead.
# Web UI (recommended): opens http://127.0.0.1:9999 in your browser
./bin/plgm --webui
# Headless CLI
./bin/plgmIn the UI, choose Run a generic workload, enter your MongoDB URI, and click Launch Workload. See Web UI for a step-by-step first run.
Each guide explains a feature, shows how to set it up in the Web UI step by step, and lists the matching config.yaml settings and environment variables.
| Guide | What it covers |
|---|---|
| Web UI | Starting the UI, HTTPS, remote access over SSH, your first run, settings categories, live dashboard, and Time Machine |
| Running from the Command Line | CLI configuration, flags, --help output, and how to read the console output |
| Workloads | Default and custom workloads, saved definition library, data types, indexes and shard keys, seeding, operation mix, transactions, and sharding |
| Load Modeling | Load profiles, think time, access-pattern skew, latency heatmap, and schema inference from query logs |
| Query and Index Analysis | Post-run explain, scan efficiency, execution overhead, index recommendations, and latency targets |
| Compare Runs | Throughput and latency of several runs or servers on the same charts, with examples; saving and loading run settings is in the Web UI guide |
| Trends and History | Run history, labels and pinning, comparing runs, run matrix, sharing, and where history is stored |
| Record and Replay | Upgrade testing: recording, replaying, deterministic traffic, outcomes, comparing replays, multi-target replay, and importing captured traffic |
| Reports and Exports | CSV metrics export, JSON summary, and HTML run report |
| Raw Injector | High-throughput hardware stress test mode |
| Performance Tuning | CPU, concurrency, connection pooling, batch sizes, timeouts, iterations, driver options, and TLS |
| Configuration Reference | Every config.yaml setting and environment variable in one table |
More references:
INSIGHTS.md: the full query analysis reference (explain support matrix, statuses, confidence model, troubleshooting, and limitations).- Docker & Kubernetes Guide: building images and running PLGM jobs inside Kubernetes (recommended for accurate network latency testing).
TESTING.md: unit and integration tests, including a Docker-based MongoDB setup.CHANGELOG.md: release notes.
This application is not supported by Percona. It has been provided as a community contribution and is not covered under any Percona services agreement.