An agent-friendly load tester for HTTP and gRPC
Gmeter sends requests on a fixed schedule and times each one from the moment it was due, so a stalled server cannot hide its slowest requests. Run it from the command line, from a Go test, or as an MCP server that an AI agent can use within limits you set.
brew install optimm/tap/gmetergo install github.com/optimm/Gmeter/cmd/gmeter@latest. Windows zips and a Docker image (ghcr.io/optimm/gmeter) are on the releases page.
897µs or 505.2ms
Same run, different clock
Both numbers are the p90 of the same test: one timed from when each request was sent, the other from when it was due. Most load testers only show you the first. Gmeter keeps sending on schedule through a stall and times every request from the moment it was due, so the stall lands in your p99 instead of vanishing.
A server that answers instantly, except for a one-second freeze two seconds in, tested at 200 requests a second for 5 seconds. Each dot is a request, placed at the time it was sent or due, and as high as its latency. The p90s are from the real run in the README; the dots are thinned to 30 a second so you can see them.
The requests a stall delays are the ones most testers never send
Most load testers send a request, wait for the reply, then send the next. When the server freezes, they freeze with it. The requests real users would have sent during that second are never sent, so they are never measured, and the percentiles come out looking healthy. This is called coordinated omission.
Gmeter schedules request n at start + n / rate and never waits for the server to
decide. A request that goes out late, because the server or Gmeter itself was busy, is still timed from when
it was due. Both numbers are in every report, side by side, so you can see how much of the latency came from
the stall.
- service p90, from send
- 897µs
- corrected p90, from due time
- 505.2ms
- requests due during the freeze
- 200 of 1,000
- corrected p99 with 20 or 2 workers
- 952ms, 957ms
Nine ways in, one honest clock
Run at a rate, a step test or a ramp
Constant rate, -stages for steps and ramps, Poisson arrivals with a seed you can replay. The
report has corrected and service latency, a per-second timeline that puts a time on every spike, a breakdown
of where each request's time went, and a line where Gmeter checks its own timing. For a server that asks the client
for a certificate, give -cert and -key.
$ gmeter -rate 200 -duration 5s -workers 20 http://127.0.0.1:18080/ requests 1000 scheduled 1000 ok 0 bad status 0 failed 0 dropped achieved 200.1 rps (target 200) over 5.00s generator timer lag p99 1.1ms, max 14.3ms late 163 (16.3%) latency, corrected (from each request's intended send time) p50 572µs p90 505.2ms p99 951.6ms p99.9 996.7ms max 1.00s latency, service (from when the request was actually sent) p50 518µs p90 897µs p99 951.6ms p99.9 996.7ms max 1.00s timeline (1s windows) p99 ▁▁█▁▁ worst 992.0ms in the window ending at 3.0s rps ▆▄█▆ lowest 114 in the window ending at 2.0s
Reading the report, where the time goes and load profiles in the README.
Find the most it can take within your target
Give it a latency target and an error budget. It doubles the rate until a trial misses, bisects, then re-runs the answer to see whether it holds. It also tells you when the answer needs a caveat, and when the limit it hit was Gmeter's rather than the server's.
$ gmeter find -slo p99=50ms -trial 5s -warmup 1s http://127.0.0.1:18082/ # phase rate p99 errors result 1 grow 100 8.2ms 0.0% pass 2 grow 200 7.7ms 0.0% pass 3 grow 400 9.1ms 0.0% pass 4 grow 800 183.1ms 0.0% FAIL p99 is 183.1ms, over the 50ms target 5 bisect 600 12.7ms 0.0% pass 6 bisect 700 26.8ms 0.0% pass 7 bisect 750 52.9ms 0.0% FAIL p99 is 52.9ms, over the 50ms target 8 bisect 725 34.5ms 0.0% pass 9 confirm 725 39.1ms 0.0% pass 10 confirm 725 38.8ms 0.0% pass result the highest rate meeting p99 ≤ 50ms is about 725 rps held in 2 of 2 re-runs at 725 rps
Replay production traffic, bursts included
Feed it an nginx or Apache access log, or JSON Lines, and it sends each request when it was recorded, with
the real mix of endpoints. Results come per endpoint. It sends only GET and HEAD
unless you say otherwise, so a log full of DELETEs can't change your staging data by accident.
# a 10-second trace at about 300 rps, against a server with four slots
endpoints, busiest first (corrected latency)
endpoint scheduled bad failed p50 p99 max
GET /orders/:id 1961 0 0 4.3ms 72.9ms 89.0ms
GET /search 625 0 0 42.6ms 105.3ms 118.9ms
GET /users/:id/cart 459 0 0 4.3ms 70.6ms 80.5ms
The same 4,000 requests at 400 a second on average gave a p99 of 5.4ms when evenly spaced and 121.1ms at their recorded pace, because the bursts queue. An average rate hides that.
Compare two runs, and fail the build on a regression
Every run can be saved with its full latency histograms. diff compares two runs from those
histograms, warns when the runs weren't set up the same way, and with -threshold exits 1 when
p99 grew too much.
$ gmeter diff -threshold 20 before.json after.json A B change achieved rps 200.1 200.1 +0.0% latency, corrected p50 442µs 572µs +29.3% p99 3.0ms 951.6ms +31966.3% share of B's requests that are slower than A's percentiles slower than A's p99 (3.0ms): 21.8% (at most 1.0% if nothing changed)
The last line is something two percentiles can't tell you: how many more of your requests got slow.
gRPC on the same clock
Call any unary method by name. The schema comes from server reflection or a descriptor set, so there's no code to generate. The request is checked against the method's input type before anything is sent, and the results are counted by status code.
$ gmeter grpc -plaintext -call gmeter.demo.Echo/Say \
-data '{"name":"ann","delay_ms":5}' -rate 1000 -duration 10s 127.0.0.1:18097
requests 10000 scheduled 10000 ok 0 bad status 0 failed 0 dropped
achieved 999.4 rps (target 1000) over 10.01s
codes OK: 10000
generator timer lag p99 417ns, max 1.3ms late 1 (0.0%)
latency, corrected (from each request's intended send time)
p50 5.2ms p90 5.3ms p99 5.3ms p99.9 6.2ms max 8.3ms
More load than one machine can send
When the generator runs out of CPU, its requests go out late and the report blames the server. Gmeter warns
you when that happens. To fix it, run gmeter agent on a few machines and give the controller
-agents. The agents send back full histograms and the controller adds them up, so the merged
p99 is the p99 of every request, never an average of p99s.
$ export GMETER_TOKEN='a long random password' $ gmeter -agents gen1:7070,gen2:7070,gen3:7070,gen4:7070 -rate 40000 -duration 10s -workers 64 http://target/ # measured on one 10-core Mac: 40,000 rps for 10s, two runs where two are given generator achieved corrected p99 late one CPU 33,265 rps 2.00s, 2.02s 100% four agents, one CPU each 39,998 rps 579µs, 4.4ms 0.6%, 1.0% no CPU limit (reference) 39,992 rps 364µs 0.5%
Every request, and a chart you can attach to a ticket
The summary says how the run went. -results keeps one row per request: when it was due, sent and
finished, both latencies, and the status or failure. gmeter plot turns the file into one HTML page
with no outside dependencies, so it opens offline. Where its red and blue lines part, requests waited before
they were sent.
$ gmeter -rate 200 -duration 10s -results run.csv http://localhost:8080/ $ gmeter plot run.csv gmeter plot: wrote run.html
The page shows latency over time by both clocks, the load over time, the latency distribution, and what answered and what failed. A file of millions of rows takes bounded memory.
Run a load from a Go test, and fail it on the numbers
The engine is a Go package, for HTTP and unary gRPC: no process to start and no output to parse. Meets uses the same
rules as gmeter find, so it also fails when Gmeter couldn't keep time itself. FindCapacity
is the rate search as a function.
$ go get github.com/optimm/Gmeter res, err := gmeter.Run(ctx, gmeter.Config{URL: srv.URL, Rate: 500, Duration: 10 * time.Second}) err = res.Meets(gmeter.SLO{Quantile: 0.99, Latency: 80 * time.Millisecond, MaxErrorRate: 0.001}) target missed: errors 0.4% over the 0.1% budget; p99 is 212ms, over the 80ms target
Let an AI agent load test, with limits you set
gmeter mcp serves Gmeter over the Model Context Protocol. An agent can run a load, find the highest
rate a service holds, check a latency target and compare two runs. Each answer starts with a sentence and a
verdict, and says when Gmeter could not keep time itself, so the agent doesn't draw a conclusion from numbers
that were the generator's.
An agent that can send load is a risk, so by default it can target only your own machine, and its rate, run time and connections are capped. Cloud metadata addresses are refused even when you allow everything else.
$ claude mcp add gmeter -- gmeter mcp -allow staging.example.com -max-rate 500 check_slo url=http://127.0.0.1:8080/ rate=100 duration=1s slo=p99=200ms Met p99=200ms: corrected p99 7.0ms over 100 requests. load_test url=http://93.184.216.34/ rate=10 duration=1s 93.184.216.34 is not allowed: an agent may only target loopback unless the server was started with -allow 93.184.216.34
How it compares
There are excellent load testers already. Gmeter is for when the question is "what latency will my users actually see at this load", and you want an answer you don't have to second-guess.
| Feature | Gmeter | wrk | wrk2 | Vegeta | k6 | Locust |
|---|---|---|---|---|---|---|
| Sends on a fixed schedule, whatever the server does | Yes | No | Yes | Yes | With the arrival-rate executors | No |
| Measures latency from when each request was due | Yes | No | Yes | From when sent; adds workers to stay on time | From when sent; iterations it can't start are dropped and counted | No |
| Checks its own timing and says when it is the bottleneck | Timer lag and late sends, with warnings | No | No | No | Counts dropped iterations | Warns on high CPU |
| Searches for the highest rate that meets a latency target | Yes | No | No | No | No | No |
| Replays an access log at its recorded pace | Yes, per endpoint | No | No | Its requests, not their timing | By scripting it | By scripting it |
| Splits each request into dns, connect, tls, send, wait, transfer | Yes, with Gmeter's own queueing too | No | No | No | Yes | No |
| Compares two runs and gates a build on the difference | Yes, from full histograms | No | No | No | Pass or fail thresholds per run | No |
| HTTP/2 | Yes, TLS and h2c | No | No | Yes | Yes | Not built in |
| gRPC | Unary | No | No | No | Yes, streaming too | With a custom client |
| Several machines, one merged result | Yes, histograms added | No | No | Merge the result files yourself | k6 Operator or Grafana Cloud | Yes, built in |
| Importable as a Go library | Yes, with an SLO check | No | No | Yes | Extensions are Go; tests are JavaScript | Python, not Go |
| Scripted user journeys | No | Lua | Lua | No | JavaScript | Python |
Based on each project's documentation and source as of November 2026. If a cell is out of date, open an issue and it will be fixed.
When to use something else
- Multi-step user journeys with logins, state and think time: k6 or Locust.
- Streaming gRPC methods: k6 or ghz.
- A browser in the loop: k6's browser module or Playwright.
- A hosted dashboard for a team to share: Grafana Cloud k6 or Locust's web UI.
Under the hood
- Never averages percentiles
- Every result keeps its full log-linear histogram: about 250KB, with at most 0.1% error at any size. Stages, windows and agents are combined by adding histograms together.
- No drift over millions of requests
- Request n's due time is computed from n, never by adding up intervals, so rounding errors can't accumulate. A generator that falls behind catches up, and each late request keeps its due time.
- Precise timing, at a small CPU cost
- The scheduler sleeps, then busy-waits the last 200µs. At 100 rps that brought the corrected p50 from 2.4ms down to 601µs, against a service p50 of 541µs. The busy-wait is capped at a quarter of a core and turns itself off above about 5,000 rps.
- Recording without locks
- Each worker records into its own atomic histogram, padded to a 128-byte cache line, and a sampler reads them. With 8 goroutines recording at once, padding took a record from 2.0–3.1ns down to 0.92ns.
- Three dependencies, all pinned
- Everything is Go's standard library except gRPC support, which pins grpc v1.85.0 and protobuf v1.36.12, and the MCP server, which pins the official Go SDK v1.8.0.
- Safe by default
- Replays send only GET and HEAD unless you say otherwise. Agents listen on localhost unless told otherwise, and read their password from an environment variable, never a flag. Passwords in URLs are redacted everywhere they're printed or saved. The MCP server targets only loopback until you allow more, and caps the load an agent can ask for.
Point it at something
$ brew install optimm/tap/gmeter $ gmeter -rate 500 -duration 30s http://localhost:8080/health $ gmeter -stages '30s@200,30s@400,30s@800' -arrivals poisson http://localhost:8080/ $ gmeter find -slo p99=50ms http://localhost:8080/health
Every flag and every caveat is in the README, with real output from real runs.