1# Benchmark
2
3gRPC-Go comes with a set of benchmarking utilities to measure performance.
4These utilities can be found in the `benchmark` directory within the project's
5root directory.
6
7The main utility, aptly named `benchmain`, supports a host of configurable
8parameters to simulate various environments and workloads. For example, if your
9server's workload is primarily streaming RPCs with large messages with
10compression turned on, invoking `benchmain` in the following way may closely
11simulate your application:
12
13```bash
14$ go run google.golang.org/grpc/benchmark/benchmain/main.go \
15    -workloads=streaming \
16  	-reqSizeBytes=1024 \
17  	-respSizeBytes=1024 \
18  	-compression=gzip
19```
20
21Pass the `-h` flag to the `benchmain` utility to see other flags and workloads
22that are supported.
23
24## Varying Payload Sizes (Weighted Random Distribution)
25
26The `benchmain` utility supports two flags, `-reqPayloadCurveFiles` and
27`-respPayloadCurveFiles`, that can be used to specify a histograms representing
28a weighted random distribution of request and response payload sizes,
29respectively. This is useful to simulate workloads with arbitrary payload
30sizes.
31
32The options takes a comma-separated list of file paths as value. Each file must
33be a valid CSV file with three columns in each row. Each row represents a range
34of payload sizes (first two columns) and the weight associated with that range
35(third column). For example, consider the below file:
36
37```csv
381,32,12.5
39128,256,12.5
401024,2048,25.0
41```
42
43Assume that `benchmain` is invoked like so:
44
45```bash
46$ go run google.golang.org/grpc/benchmark/benchmain/main.go \
47    -workloads=unary \
48  	-reqPayloadCurveFiles=/path/to/csv \
49  	-respPayloadCurveFiles=/path/to/csv
50```
51
52This tells the `benchmain` utility to generate unary RPC requests with a 25%
53probability of payload sizes in the ranges 1-32 bytes, 25% probability in the
54128-256 bytes range, and 50% probability in the 1024-2048 bytes range. RPC
55requests outside these ranges will not be generated.
56
57You may specify multiple CSV files delimited by a comma. The utility will
58execute the benchmark with each combination independently. That is, the
59following command will execute four benchmarks:
60
61```bash
62$ go run google.golang.org/grpc/benchmark/benchmain/main.go \
63    -workloads=unary \
64  	-reqPayloadCurveFiles=/path/to/csv1,/path/to/csv2 \
65  	-respPayloadCurveFiles=/path/to/csv3,/path/to/csv4
66```
67
68You may also combine `PayloadCurveFiles` with `SizeBytes` options. For example:
69
70```
71$ go run google.golang.org/grpc/benchmark/benchmain/main.go \
72    -workloads=unary \
73  	-reqPayloadCurveFiles=/path/to/csv \
74  	-respSizeBytes=1
75```
76