autocannon

autocannon

An HTTP/1.1 benchmarking tool written in node, greatly inspired by [wrk][wrk] and [wrk2][wrk2], with support for HTTP pipelining and HTTPS. On my box, autocannon can produce more load than wrk and wrk2, see limitations for more details.

• Installation
• Usage
• API
• Acknowledgements
• License

Install

npm i autocannon -g

or if you want to use the API or as a dependency:

npm i autocannon --save

Usage

Command Line

…

autocannon outputs data in tables like this:

…

There are two tables: one for the request latency, and one for the request volume.

The latency table lists the request times at the 2.5% percentile, the fast outliers; at 50%, the median; at 97.5%, the slow outliers; at 99%, the very slowest outliers. Here, lower means faster.

The request volume table lists the number of requests sent and the number of bytes downloaded. These values are sampled once per second. Higher values mean more requests were processed. In the above example, 2.29 MB was downloaded in 1 second in the worst case (slowest 1%). Since we only ran for 10 seconds, there are just 10 samples, the Min value and the 1% and 2.5% percentiles are all the same sample. With longer durations these numbers will differ more.

When passing the -l flag, a third table lists all the latency percentiles recorded by autocannon:

…

This can give some more insight if a lot (millions) of requests were sent.

Programmatically

'use strict'

const autocannon = require('autocannon')

autocannon({
  url: 'http://localhost:3000',
  connections: 10, //default
  pipelining: 1, // default
  duration: 10 // default
}, console.log)

// async/await
async function foo () {
  const result = await autocannon({
    url: 'http://localhost:3000',
    connections: 10, //default
    pipelining: 1, // default
    duration: 10 // default
  })
  console.log(result)
}

Workers

In workers mode, autocannon uses instances of Node's Worker class to execute the load tests in multiple threads.

The amount and connections parameters are divided amongst the workers. If either parameter is not integer divisible by the number of workers, the per-worker value is rounded to the lowest integer, or set to 1, whichever is the higher. All other parameters are applied per-worker as if the test were single-threaded.

NOTE: Unlike amount and connections, the "overall" parameters, maxOverallRequests and overallRate, are applied per worker. For example, if you set connections to 4, workers to 2 and maxOverallRequests to 10, each worker will receive 2 connections and a maxOverallRequests of 10, resulting in 20 requests being sent.

'use strict'

const autocannon = require('autocannon')

autocannon({
  url: 'http://localhost:3000',
  connections: 10, //default
  pipelining: 1, // default
  duration: 10, // default
  workers: 4
}, console.log)

NOTE: When in workers mode, you need to pass in an absolute file path to all the options that accept a function. This is because a function passed into the main process can not be cloned and passed to the worker. So instead, it needs a file that it can require. The options with this behaviour are shown in the below example

'use strict'

const autocannon = require('autocannon')

autocannon({
  // ...
  workers: 4,
  setupClient: '/full/path/to/setup-client.js',
  verifyBody: '/full/path/to/verify-body.js'
  requests: [
    {
      // ...
      onResponse: '/full/path/to/on-response.js'
    },
    {
      // ...
      setupRequest: '/full/path/to/setup-request.js'
    }
  ]
}, console.log)

API

autocannon(opts[, cb])

Start autocannon against the given target.

• opts: Configuration options for the autocannon instance. This can have the following attributes. REQUIRED.
  • url: The given target. Can be HTTP or HTTPS. More than one URL is allowed, but it is recommended that the number of connections is an integer multiple of the URL. REQUIRED.
  • socketPath: A path to a Unix Domain Socket or a Windows Named Pipe. A url is still required to send the correct Host header and path. OPTIONAL.
  • workers: Number of worker threads to use to fire requests.
  • connections: The number of concurrent connections. OPTIONAL default: 10.
  • duration: The number of seconds to run the autocannon. Can be a timestring. OPTIONAL default: 10.
  • amount: A Number stating the number of requests to make before ending the test. This overrides duration and takes precedence, so the test won't end until the number of requests needed to be completed is completed. OPTIONAL.
  • sampleInt: The number of milliseconds to elapse between taking samples. This controls the sample interval, & therefore the total number of samples, which affects statistical analyses. default: 1.
  • timeout: The number of seconds to wait for a response before. OPTIONAL default: 10.
  • pipelining: The number of pipelined requests for each connection. Will cause the Client API to throw when greater than 1. OPTIONAL default: 1.
  • bailout: The threshold of the number of errors when making the requests to the server before this instance bail's out. This instance will take all existing results so far and aggregate them into the results. If none passed here, the instance will ignore errors and never bail out. OPTIONAL default: undefined.
  • method: The HTTP method to use. OPTIONAL default: 'GET'.
  • title: A String to be added to the results for identification. OPTIONAL default: undefined.
  • body: A String or a Buffer containing the body of the request. Insert one or more randomly generated IDs into the body by including [<id>] where the randomly generated ID should be inserted (Must also set idReplacement to true). This can be useful in soak testing POST endpoints where one or more fields must be unique. Leave undefined for an empty body. OPTIONAL default: undefined.
  • form: A String or an Object containing the multipart/form-data options or a path to the JSON file containing them
  • headers: An Object containing the headers of the request. OPTIONAL default: {}.
  • initialContext: An object that you'd like to initialize your context with. Check out an example of initializing context. OPTIONAL
  • setupClient: A Function which will be passed the Client object for each connection to be made. This can be used to customise each individual connection headers and body using the API shown below. The changes you make to the client in this function will take precedence over the default body and headers you pass in here. There is an example of this in the samples folder. OPTIONAL default: function noop () {}. When using workers, you need to supply a file path that default exports a function instead (Check out the workers section for more details).
  • verifyBody: A Function which will be passed the response body for each completed request. Each request, whose verifyBody function does not return a truthy value, is counted in mismatches. This function will take precedence over the expectBody. There is an example of this in the samples folder. When using workers, you need to supply a file path that default exports a function (Check out the workers section for more details).
  • maxConnectionRequests: A Number stating the max requests to make per connection. amount takes precedence if both are set. OPTIONAL
  • maxOverallRequests: A Number stating the max requests to make overall. Can't be less than connections. maxConnectionRequests takes precedence if both are set. OPTIONAL
  • connectionRate: A Number stating the rate of requests to make per second from each individual connection. No rate limiting by default. OPTIONAL
  • overallRate: A Number stating the rate of requests to make per second from all connections. connectionRate takes precedence if both are set. No rate limiting by default. OPTIONAL
  • ignoreCoordinatedOmission: A Boolean which disables the correction of latencies to compensate for the coordinated omission issue. Does not make sense when no rate of requests has been specified (connectionRate or overallRate). OPTIONAL default: false.
  • reconnectRate: A Number that makes the individual connections disconnect and reconnect to the server whenever it has sent that number of requests. OPTIONAL
  • requests: An Array of Objects which represents the sequence of requests to make while benchmarking. Can be used in conjunction with the body, headers and method params above. Check the samples folder for an example of how this might be used. OPTIONAL. Contained objects can have these attributes:
    • body: When present, will override opts.body. OPTIONAL
    • headers: When present, will override opts.headers. OPTIONAL
    • method: When present, will override opts.method. OPTIONAL
    • path: When present, will override opts.path. OPTIONAL
    • setupRequest: A Function you may provide to mutate the raw request object, e.g. request.method = 'GET'. It takes request (Object) and context (Object) parameters, and must return the modified request. When it returns a falsey value, autocannon will restart from first request. When using workers, you need to supply a file path that default exports a function instead (Check out workers section for more details) OPTIONAL
    • onResponse: A Function you may provide to process the received response. It takes status (Number), body (String) context (Object) parameters and headers (Key-Value Object). When using workers, you need to supply a file path that default exports a function instead (Check out workers section for more details) OPTIONAL
  • har: an Object of parsed HAR content. Autocannon will extra and use entries.request: requests, method, form and body options will be ignored. NOTE: you must ensure that entries are targeting the same domain as url option. OPTIONAL
  • idReplacement: A Boolean which enables the replacement of [<id>] tags within the request body with a randomly generated ID, allowing for unique fields to be sent with requests. Check out an example of programmatic usage that can be found in the samples. OPTIONAL default: false
  • forever: A Boolean which allows you to setup an instance of autocannon that restarts indefinitely after emitting results with the done event. Useful for efficiently restarting your instance. To stop running forever, you must cause a SIGINT or call the .stop() function on your instance. OPTIONAL default: false
  • servername: A String identifying the server name for the SNI (Server Name Indication) TLS extension. OPTIONAL default: Defaults to the hostname of the URL when it is not an IP address.
  • excludeErrorStats: A Boolean which allows you to disable tracking non-2xx code responses in latency and bytes per second calculations. OPTIONAL default: false.
  • expectBody: A String representing the expected response body. Each request whose response body is not equal to expectBodyis counted in mismatches. If enabled, mismatches count towards bailout. OPTIONAL
  • tlsOptions: An Object that is passed into tls.connect call ([Full list of options](htt