grpcannon

README

grpcannon

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

Demo

Install

Download a prebuilt executable binary from the releases page.

Usage

Usage: grpcannon [options...] <host>
Options:
  -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.

Examples

A simple unary call:

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

Custom number of requests and concurrency:

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

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"}]' 0.0.0.0:50051

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 0.0.0.0:50051

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": [
        "/path/to/protos"
    ],
    "n": 4000,
    "c": 40,
    "host": "0.0.0.0:50051"
}

Output

Sample standard output of summary of the results:

Summary:
  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
1.43,OK,
0.39,OK,
0.36,OK,
0.50,OK,
0.36,OK,
0.40,OK,
0.37,OK,
0.34,OK,
0.35,OK,
0.32,OK,
...

Credit

Icon made by Freepik from www.flaticon.com is licensed by CC 3.0 BY

License

Apache-2.0

Documentation

Overview

Package grpcannon provides gRPC benchmarking functionality

Index

• type Bucket
• type LatencyDistribution
• type Options
• type Report
• type Reporter
  • func (r *Reporter) Finalize(total time.Duration) *Report
  • func (r *Reporter) Run()
• type Requester
  • func New(mtd *desc.MethodDescriptor, c *Options) (*Requester, error)
  • func (b *Requester) Finish() *Report
  • func (b *Requester) Run() (*Report, error)
  • func (b *Requester) Stop()
• type ResultDetail

Types

type Bucket

type Bucket struct {
	Mark      float64 // The Mark for histogram bucket in seconds
	Count     int     // The count in the bucket
	Frequency float64 // The frequency of results in the bucket as a decimal percentage
}

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