ghz: Load Test a gRPC Endpoint in CI

ghz benchmarks a gRPC method: --call selects the method, -n sets total requests, -c sets concurrency, and -d supplies the request body.

ghz is the standard gRPC load generator. A small ghz run in CI catches latency or error-rate regressions before they reach production traffic.

What it does

ghz opens -c concurrent connections, sends -n total requests (or runs for -z duration) to the method named by --call, and prints a latency distribution plus status-code counts. It resolves the schema via reflection, or from --proto/--protoset, much like grpcurl.

Common usage

Terminal

ghz --insecure \
  --proto proto/api/v1/user.proto \
  --call acme.api.v1.UserService.GetUser \
  -d '{"id":"42"}' \
  -n 2000 -c 50 \
  localhost:50051

# reflection + run for a fixed duration
ghz --insecure --call acme.api.v1.UserService.GetUser \
  -d '{"id":"42"}' -z 30s -c 20 localhost:50051

Flags and options

Flag	What it does
--call <method>	Fully qualified method, e.g. pkg.Service.Method
-n <count>	Total number of requests to send
-c <count>	Number of concurrent workers
-z <duration>	Run for a duration instead of a fixed count
-d <json>	Request data as JSON (or @file)
--insecure	Cleartext connection (no TLS)
--proto / --protoset	Schema source when reflection is unavailable

In CI

Keep CI runs short and bounded (-n or -z small) so the job stays fast; use ghz mainly to detect regressions, not to find absolute peak throughput on a noisy shared runner. Note --call uses dots (Service.Method), unlike grpcurl which uses a slash (Service/Method).

Common errors in CI

"rpc error: code = Unavailable desc = connection error: ... connection refused" means the target is down or the port is wrong. "rpc error: code = Unimplemented" usually means a wrong --call value (check dots vs slash) or reflection-off with no --proto. "failed to load proto: ... no such file" means a bad --proto/--import-paths. A high "Unavailable" count under load can mean you exceeded the server's max concurrent streams.