package module
Version: v0.3.1 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 17, 2018 License: Apache-2.0 Imports: 19 Imported by: 0




build status Go Report Card

Simple gRPC benchmarking and load testing tool inspired by hey and grpcurl.




Download a prebuilt executable binary from the releases page.


Usage: grpcannon [options...] <host>
  -proto	The protocol buffer file.
  -protoset	The compiled protoset file. Alternative to proto. -proto takes precedence.
  -call		A fully-qualified method name in 'service/method' or 'service.method' format.
  -cert		The file containing the CA root cert file.
  -cname	An override of the expect Server Cname presented by the server.
  -config	Path to the config JSON file.

  -c  Number of requests to run concurrently. Total number of requests cannot
	  be smaller than the concurrency level. Default is 50.
  -n  Number of requests to run. Default is 200.
  -q  Rate limit, in queries per second (QPS). Default is no rate limit.
  -t  Timeout for each request in seconds. Default is 20, use 0 for infinite.
  -z  Duration of application to send requests. When duration is reached,
      application stops and exits. If duration is specified, n is ignored.
      Examples: -z 10s -z 3m.

  -d  The call data as stringified JSON.
  -D  Path for call data JSON file. For example, /home/user/file.json or ./file.json.
  -m  Request metadata as stringified JSON.
  -M  Path for call metadata JSON file. For example, /home/user/metadata.json or ./metadata.json.

  -o  Output path. If none provided stdout is used.
  -O  Output type. If none provided, a summary is printed.
      "csv" is the only supported alternative. Dumps the response
	  metrics in comma-separated values format.

  -i  Comma separated list of proto import paths. The current working directory and the directory
	  of the protocol buffer file are automatically added to the import list.

  -T  Connection timeout in seconds for the initial connection dial. Default is 10.
  -L  Keepalive time in seconds. Only used if present and above 0.

  -cpus		Number of used cpu cores. (default for current machine is 8 cores)

  -v  Print the version.

Alternatively all settings can be set via grpcannon.json file if present in the same path as the grpcannon executable. A custom configuration file can be specified using -config option.


A simple unary call:

grpcannon -proto ./greeter.proto -call helloworld.Greeter.SayHello -d '{"name":"Joe"}'

Custom number of requests and concurrency:

grpcannon -proto ./greeter.proto -call helloworld.Greeter.SayHello -d '{"name":"Joe"}' -n 2000 -c 20

Client streaming data can be sent as an array, each element representing a single message:

grpcannon -proto ./greeter.proto -call helloworld.Greeter.SayHelloCS -d '[{"name":"Joe"},{"name":"Kate"},{"name":"Sara"}]'

If a single object is given for data it is sent as every message.

We can also use .protoset files which can bundle multiple protoco buffer files into one binary file.

Create a protoset

protoc --proto_path=. --descriptor_set_out=bundle.protoset *.proto

And then use it as input to grpcannon with -protoset option:

./grpcannon -protoset ./bundle.protoset -call helloworld.Greeter.SayHello -d '{"name":"Bob"}' -n 1000 -c 10

Note that only one of -proto or -protoset options will be used. -proto takes precedence.

Using a custom config file:

grpcannon -config ./config.json

Example grpcannon.json

    "proto": "/path/to/greeter.proto",
    "call": "helloworld.Greeter.SayHello",
    "n": 2000,
    "c": 50,
    "d": {
        "name": "Joe"
    "i": [
    "n": 4000,
    "c": 40,
    "host": ""


Sample standard output of summary of the results:

  Count:	2000
  Total:	345.52 ms
  Slowest:	15.41 ms
  Fastest:	0.66 ms
  Average:	6.83 ms
  Requests/sec:	5788.35

Response time histogram:
  0.664 [1]	|
  2.138 [36]	|∎
  3.613 [14]	|
  5.087 [65]	|∎∎
  6.561 [1305]	|∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎
  8.035 [274]	|∎∎∎∎∎∎∎∎
  9.509 [66]	|∎∎
  10.983 [0]	|
  12.458 [59]	|∎∎
  13.932 [130]	|∎∎∎∎
  15.406 [50]	|∎∎

Latency distribution:
  10% in 5.18 ms
  25% in 5.51 ms
  50% in 6.10 ms
  75% in 6.72 ms
  90% in 12.19 ms
  95% in 13.26 ms
  99% in 14.73 ms
Status code distribution:
  [OK]	2000 responses

Alternatively with -O csv flag we can get detailed listing in csv format:

duration (ms),status,error


Icon made by Freepik from is licensed by CC 3.0 BY





Package grpcannon provides gRPC benchmarking functionality



This section is empty.


This section is empty.


This section is empty.


type Bucket

type Bucket struct {
	Mark      float64
	Count     int
	Frequency float64

Bucket holds histogram data

type LatencyDistribution

type LatencyDistribution struct {
	Percentage int
	Latency    time.Duration

LatencyDistribution holds latency distribution data

type Options

type Options struct {
	Host          string
	Cert          string
	CName         string
	N             int
	C             int
	QPS           int
	Z             time.Duration
	Timeout       int
	DialTimtout   int
	KeepaliveTime int
	Data          interface{}
	Metadata      *map[string]string

Options represents the request options

type Report

type Report struct {
	Count   uint64
	Total   time.Duration
	Average time.Duration
	Fastest time.Duration
	Slowest time.Duration
	Rps     float64

	ErrorDist      map[string]int
	StatusCodeDist map[string]int

	LatencyDistribution []LatencyDistribution
	Histogram           []Bucket
	Details             []ResultDetail

Report holds the data for the full test

type Reporter

type Reporter struct {
	// contains filtered or unexported fields

Reporter gethers all the results

func (*Reporter) Finalize

func (r *Reporter) Finalize(total time.Duration) *Report

Finalize all the gathered data into a final report

func (*Reporter) Run

func (r *Reporter) Run()

Run runs the reporter

type Requester

type Requester struct {
	// contains filtered or unexported fields

Requester is used for doing the requests

func New

func New(mtd *desc.MethodDescriptor, c *Options) (*Requester, error)

New creates new Requester

func (*Requester) Finish

func (b *Requester) Finish() *Report

Finish finishes the test run

func (*Requester) Run

func (b *Requester) Run() (*Report, error)

Run makes all the requests and returns a report of results It blocks until all work is done.

func (*Requester) Stop

func (b *Requester) Stop()

Stop stops the test

type ResultDetail

type ResultDetail struct {
	Latency time.Duration
	Error   string
	Status  string

ResultDetail data for each result


Path Synopsis
Package helloworld is a generated protocol buffer package.
Package helloworld is a generated protocol buffer package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL