Gocannon is a lightweight HTTP benchmarking tool, intended to measure changes in backend application performance over time. It keeps a detailed log of each request that is sent, not just the histogram of their latencies.
The easiest way to install Gocannon is to download pre-built binaries for your platform that are automatically attached to each release. If you wish to build Gocannon from source, clone this repository and run go build. Alternatively, you can run Gocannon as a container using jauderho/gocannon image.
usage: gocannon [<flags>] <target>
Flags:
--help Show context-sensitive help (also try --help-long and
--help-man).
-d, --duration=10s Load test duration.
-c, --connections=50 Maximum number of concurrent connections.
--cpus Maximum number of logical CPUs that can be utilised.
Defaults to the number of available CPU threads (or
the GOMAXPROCS env variable).
-t, --timeout=200ms HTTP client timeout.
-m, --mode="reqlog" Statistics collection mode: reqlog (logs each request)
or hist (stores histogram of completed requests
latencies).
-o, --output=file.csv File to save the request log in CSV format (reqlog
mode) or a text file with raw histogram data (hist
mode).
-i, --interval=250ms Interval for statistics calculation (reqlog mode).
--preallocate=1000 Number of requests in req log to preallocate memory
for per connection (reqlog mode).
--method=GET The HTTP request method (GET, POST, PUT, PATCH or
DELETE).
-b, --body="{data..." HTTP request body.
-h, --header="k:v" ... HTTP request header(s). You can set more than one
header by repeating this flag.
--trust-all Omit SSL certificate validation.
-f, --format=default Load test report format. Either 'default' (verbose),
'json' or 'yaml'. When json or yaml is specified,
apart from the load test results, no additional info
will be written to std out.
--plugin=/to/p.so Plugin to run Gocannon with (path to .so file).
--version Show application version.
Args:
<target> HTTP target URL with port (i.e. http://localhost:80/test or
https://host:443/x)
Below is an example of a load test conducted using gocannon against an Express.js server (notice the performance improvement over time under sustained load):
> gocannon http://localhost:3000/static -d 3s -c 50
Attacking http://localhost:3000/static with 50 connections over 3s
gocannon goes brr...
Total Req: 14990
Req/s: 4996.67
Interval stats: (interval = 250ms)
|--REQS--| |------------------------LATENCY-------------------------|
Count AVG P50 P75 P90 P99
673 18.004823ms 17.768106ms 18.810048ms 20.358396ms 31.970312ms
777 16.090895ms 16.096573ms 17.475942ms 18.049402ms 19.867212ms
922 13.630393ms 13.573315ms 14.279727ms 15.720507ms 17.725149ms
987 12.715278ms 12.050508ms 14.378844ms 15.661408ms 20.669683ms
1137 10.997768ms 10.201962ms 11.468307ms 13.736441ms 15.374815ms
1354 9.186035ms 8.689116ms 9.831591ms 10.417963ms 11.393158ms
1412 8.889394ms 8.444931ms 8.834144ms 10.480375ms 11.886929ms
1428 8.792173ms 7.880262ms 9.580714ms 10.753837ms 14.997604ms
1599 7.817586ms 7.578824ms 7.645575ms 9.083118ms 10.047772ms
1505 8.244456ms 7.580401ms 8.307621ms 9.611815ms 17.449891ms
1617 7.745439ms 7.422272ms 7.487905ms 9.132874ms 11.457255ms
1579 7.901125ms 7.525814ms 7.655212ms 9.577895ms 10.203331ms
----------
14990 9.986321ms 8.540818ms 11.252258ms 15.309979ms 19.632593ms
Responses by HTTP status code:
200 -> 14990
Requests ended with timeout/socket error: 1
When used with the --output=filename.csv flag, raw request data (which includes the request HTTP code, starting timestamp, response timestamp both in nanoseconds since the beginning of the test as well as the ID of the connection which was used for that request) can be written into the specified csv file in the following format:
code;start;end;connection;
200;509761;30592963;0;
200;694043;34837869;0;
200;963463;36094909;0;
200;841397;37319812;0;
[...]
In the CSV output file, the requests are sorted primarily by connection ID and secondarily by response timestamp (end column).
Gocannon stores data of each completed request in a slice (one per each connection). If a given slice runs out of its initial capacity, the underlying array is re-allocated to a newly selected memory address with double the capacity. In order to minimize the performance impact of slice resizing during the load test, you can specify the number of requests in log per connection to preallocate memory for using the --preallocate flag.
There are some use cases in which request log mode is not desirable. If you don't need a detailed log of each request that was completed during the load test, you can use histogram mode using the --mode=hist flag. When using histogram mode, upon each completed request, gocannon will only save its latency in a histogram (in a manner similar to how wrk or bombardier does that). That way, memory usage of the stats collector will remain constant over the entire duration of the load test. This results in gocannon having a total memory footprint of about 3MB when conducting a load test in histogram mode (when the timeout is set to a default 200ms).
Below is an example of a load test conducted with gocannon in histogram mode:
> gocannon http://localhost:3000/static --duration=2m --mode=hist
Attacking http://localhost:3000/static with 50 connections over 2m0s
gocannon goes brr...
Total Req: 13715707
Req/s: 114297.56
|------------------------LATENCY (μs)-----------------------|
AVG P50 P75 P90 P99
436.45 278 508 925 2681
Responses by HTTP status code:
200 -> 13715707
Similarly to saving CSV output in request log mode, you can write the histogram data to a text file using the --output=filename flag. The output contains the number of hits in each latency histogram bin (having width of 1μs) truncated up until the last non-zero value:
0
0
1
1
15
45
[...]
Gocannon supports user-provided plugins, which can customize the requests sent during the load test. A custom plugin has to satisfy the GocannonPlugin interface defined in the common package, which also contains types required for plugin development. An example implementation with additional comments is provided in _example_plugin folder.
In order to build a plugin, use the following command inside its directory:
go build -buildmode=plugin -o plugin.so plugin.go
Once you obtain a shared object (.so) file, you can provide a path to it via --plugin flag. Bare in mind that a custom plugin .so file and the Gocannon binary using it must both be compiled using the same Go version.
You can use Gocannon as a library for performing programmatic load tests. Consult GoDoc for API reference and main.go for example implementation. Please bare in mind that you cannot reuse a Gocannon instance to perform multiple load tests.
- Killing non-essential background processes: Since the activity of background processes running alongside the SUT may introduce anomalies in the obtained experiment results, it is advised to disable non-essential services for the load test duration. Additionally, when conducting a load test against a SUT running on the same machine as gocannon, you may want to assign the SUT and gocannon processes to separate sets of logical cores (i.e. via
taskset) and update theGOMAXPROCSenv variable accordingly (so as to reflect the number of cores available to gocannon). - Disabling Turbo Boost, EIST and ensuring a constant CPU clock: Changes of the CPU clock over the duration of the load test may introduce inconsistencies in the collected metrics, especially given that the detection of a suitable workload after the test start and subsequent increase of the CPU clock may cause observable improvement in application throughput shortly after the start of the load test. If your goal is to measure how the application performance changes over time under sustained load, you may want to disable Turbo Boost and EIST (or their equivalents in your system) as well as ensure that the CPU clock is not being reduced at idle (i.e. by setting the CPU mode to performance via the
cpupowerlinux package). - Repeating the test runs: Performing multiple test runs improves the statistical significance of the obtained results and minimizes impact of potential one-off anomalies (i.e. background process activity during the load test) in the obtained data on the overall result. When combining data from multiple test runs, remember not to average the percentiles. Instead, place the obtained request latencies of all runs in a single dataset and calculate the desired percentiles on that dataset.
Copyright Paweł Kuffel 2021-2022, licensed under Apache 2.0 License.
The Gocannon logo contains the Go Gopher mascot which was originally designed by Renee French (http://reneefrench.blogspot.com/) and licensed under Creative Commons 3.0 Attributions license.