hey: Usage, Options & Common CI Errors
hey sends concurrent HTTP requests and reports a latency histogram.
hey is a Go-based ab replacement with cleaner output and rate limiting. It is a single static binary, which makes it easy to drop into a CI image.
What it does
hey sends -n requests (or runs for -z duration) at -c concurrency to a URL and prints a latency histogram plus a status-code distribution. With -q it rate-limits per worker, useful for steady-state tests.
Common usage
hey -n 2000 -c 50 https://example.com/
hey -z 30s -c 50 https://example.com/ # run for a duration
hey -m POST -d '{"k":"v"}' -T application/json https://api/x
hey -n 1000 -c 20 -q 10 https://example.com/ # cap 10 req/s per worker
hey -H "Authorization: Bearer ${TOKEN}" -n 500 https://api/xOptions
| Flag | What it does |
|---|---|
| -n <N> | Total number of requests |
| -c <N> | Number of concurrent workers |
| -z <dur> | Run for a duration instead of a count |
| -q <rate> | Rate limit in queries/sec per worker |
| -m <METHOD> | HTTP method (GET, POST, …) |
| -d <body> / -D <file> | Request body inline / from a file |
Common errors in CI
hey does not fail the build on non-2xx - it tallies them under "Status code distribution"; in CI you must parse that section (or count errors) to gate. "Get \"https://...\": dial tcp ... connect: connection refused" means the service is not up. "x509: certificate signed by unknown authority" on TLS - pass -disable-redirects/-insecure or trust the CA. Combining -n and -z is contradictory; pick one. The histogram is in seconds, which trips people comparing against ms SLAs.