How to Accurately Benchmark API QPS with Hey: A Step‑by‑Step Guide

Introduction

When performing API load testing, tools like ab, wrk, and autocannon lack the ability to fix a target QPS level. This guide introduces the Hey tool, which allows precise QPS‑controlled testing to better estimate capacity.

Installation

go get -u github.com/rakyll/hey
go install github.com/rakyll/hey

Usage

After installing Hey, you can run a test against your service: hey -n 10000 -c 2 -q 10 http://www.${web}.com/ Parameters:

-n 10000 : total number of requests.

-c 2 : number of workers (similar to goroutines).

-q 10 : each worker sends 10 requests per second, resulting in an expected 20 QPS overall.

The monitoring chart should reflect the expected 20 QPS (20 × 60 = 1200 requests per minute).

Increasing workers to one and setting -q 10 yields 600 requests per minute, matching expectations.

For higher loads, you can increase workers and QPS, e.g.: hey -n 10000 -c 50 -q 10 http://www.${web}.com/ This configuration targets 50 workers × 10 QPS × 60 s = 30 000 requests per minute. In practice, the observed rate was 2 200 requests per minute, indicating the server’s maximum capacity under the test conditions.

Monitoring the server showed that bandwidth was the bottleneck (1 Mbit link), while CPU stayed below 10 % and memory around 30 %.

Enabling gzip compression increased QPS from 37 to 98, shifting the bottleneck back to bandwidth. CPU usage rose to about 20 % when gzip was active.

Key observations:

Always monitor CPU, memory, and network during load tests.

If the load‑generator becomes the bottleneck, consider distributed testing across multiple machines.

Conclusion

Conducting thorough capacity evaluation with tools like Hey before deploying a Node application builds confidence in production performance and helps configure appropriate rate‑limiting based on realistic traffic models.