Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Minor documentation improvements: GoDoc, installation instructions and library usage info #33

Merged
merged 1 commit into from
Dec 27, 2021
Merged

docs: Minor documentation improvements: GoDoc, installation instructions and library usage info #33

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
# :boom: gocannon - HTTP benchmarking tool

[![CI Workflow](https://github.com/kffl/gocannon/workflows/CI/badge.svg)](https://github.com/kffl/gocannon/actions) [![Go Report Card](https://goreportcard.com/badge/github.com/kffl/gocannon)](https://goreportcard.com/report/github.com/kffl/gocannon)
[![CI Workflow](https://github.com/kffl/gocannon/workflows/CI/badge.svg)](https://github.com/kffl/gocannon/actions) [![Go Report Card](https://goreportcard.com/badge/github.com/kffl/gocannon)](https://goreportcard.com/report/github.com/kffl/gocannon) [![GoDoc](https://godoc.org/github.com/kffl/gocannon?status.svg)](https://godoc.org/github.com/kffl/gocannon)

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.

## Installation

The easiest way to install Gocannon is to download pre-built binaries for your platform that are automatically attached to each [release](https://github.com/kffl/gocannon/releases/). 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](https://hub.docker.com/r/jauderho/gocannon).

## Usage

```
Expand Down Expand Up @@ -131,6 +135,10 @@ 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.

### Using Gocannon as a library

You can use Gocannon as a library for performing programmatic load tests. Consult [GoDoc](https://godoc.org/github.com/kffl/gocannon) 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.

## Load testing recommendations

- **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 the `GOMAXPROCS` env variable accordingly (so as to reflect the number of cores available to gocannon).
Expand Down