nats bench: Benchmark and Smoke-Test NATS
nats bench <subject> --pub <n> --sub <m> --msgs <count> spins up publishers and subscribers and reports throughput, doubling as a load smoke test in CI.
Beyond a single message, nats bench confirms the server handles concurrent traffic. It is a quick way to catch a broker that connects but stalls under load.
What it does
nats bench creates the requested number of publisher and subscriber connections and sends a fixed number of messages of a given size, then prints messages per second and total time. It can target core NATS or a JetStream stream with --js.
Common usage
# 1 publisher, 100k messages, core NATS
nats bench bench.subject --pub 1 --msgs 100000 \
-s nats://localhost:4222
# publishers and subscribers together
nats bench bench.subject --pub 2 --sub 2 --msgs 50000 \
--size 128 -s nats://localhost:4222Options
| Flag | What it does |
|---|---|
| --pub <n> | Number of publisher connections |
| --sub <n> | Number of subscriber connections |
| --msgs <n> | Total messages to send |
| --size <bytes> | Message payload size |
| --js | Benchmark against JetStream instead of core NATS |
| -s <url> | Server URL |
In CI
Run a small nats bench as a post-deploy smoke test: if it completes with a sane rate, the server accepts concurrent load. Keep --msgs modest in CI so the step stays fast, and use --js only when the stream already exists.
Common errors in CI
"nats: error: no servers available for connection" means the server is not up; wait for 4222. With --js, "JetStream not enabled" means the server lacks JetStream (start nats-server -js) or the target stream is missing. A benchmark that hangs usually has more subscribers than the subject/stream can feed; check the subject matches.