Vegeta

Vegeta is a versatile HTTP load testing tool built out of a need to drill HTTP services with a constant request rate. It's over 9000!

Features

• Usable as a command line tool and a Go library.
• CLI designed with UNIX composability in mind.
• Avoids nasty Coordinated Omission.
• Extensive reporting functionality.
• Simple to use for distributed load testing.
• Easy to install and run (static binary, package managers, etc).

Install

Pre-compiled executables

Get them here.

macOS

You can install Vegeta using the Homebrew:

$ brew update && brew install vegeta

Or with MacPorts:

$ port install vegeta

Arch Linux

$ pacman -S vegeta

FreeBSD

On FreeBSD you can install Vegeta with the built in package manager because there is a Vegeta Package available.

$ pkg install vegeta

Source

git clone https://github.com/tsenart/vegeta
cd vegeta
make vegeta
mv vegeta ~/bin # Or elsewhere, up to you.

Versioning

Both the library and the CLI are versioned with SemVer v2.0.0.

After v8.0.0, the two components are versioned separately to better isolate breaking changes to each.

CLI releases are tagged with cli/vMAJOR.MINOR.PATCH and published on the GitHub releases page. As for the library, new versions are tagged with both lib/vMAJOR.MINOR.PATCH and vMAJOR.MINOR.PATCH. The latter tag is required for compatibility with go mod.

Contributing

See CONTRIBUTING.md.

Usage manual

Usage: vegeta [global flags] <command> [command flags]

global flags:
  -cpus int
        Number of CPUs to use (default = number of cpus)
  -profile string
        Enable profiling of [cpu, heap]
  -version
        Print version and exit

attack command:
  -body string
        Requests body file
  -cert string
        TLS client PEM encoded certificate file
  -chunked
        Send body with chunked transfer encoding
  -connect-to value
        A mapping of (ip|host):port to use instead of a target URL's (ip|host):port. Can be repeated multiple times.
        Identical src:port with different dst:port will round-robin over the different dst:port pairs.
        Example: google.com:80:localhost:6060
  -connections int
        Max open idle connections per target host (default 10000)
  -dns-ttl value
        Cache DNS lookups for the given duration [-1 = disabled, 0 = forever] (default 0s)
  -duration duration
        Duration of the test [0 = forever]
  -format string
        Targets format [http, json] (default "http")
  -h2c
        Send HTTP/2 requests without TLS encryption
  -header value
        Request header
  -http2
        Send HTTP/2 requests when supported by the server (default true)
  -insecure
        Ignore invalid server TLS certificates
  -keepalive
        Use persistent connections (default true)
  -key string
        TLS client PEM encoded private key file
  -laddr value
        Local IP address (default 0.0.0.0)
  -lazy
        Read targets lazily
  -max-body value
        Maximum number of bytes to capture from response bodies. [-1 = no limit] (default -1)
  -max-connections int
        Max connections per target host
  -max-workers uint
        Maximum number of workers (default 18446744073709551615)
  -name string
        Attack name
  -output string
        Output file (default "stdout")
  -prometheus-addr string
        Prometheus exporter listen address [empty = disabled]. Example: 0.0.0.0:8880
  -proxy-header value
        Proxy CONNECT header
  -rate value
        Number of requests per time unit [0 = infinity] (default 50/1s)
  -redirects int
        Number of redirects to follow. -1 will not follow but marks as success (default 10)
  -resolvers value
        List of addresses (ip:port) to use for DNS resolution. Disables use of local system DNS. (comma separated list)
  -root-certs value
        TLS root certificate files (comma separated list)
  -session-tickets
        Enable TLS session resumption using session tickets
  -targets string
        Targets file (default "stdin")
  -timeout duration
        Requests timeout (default 30s)
  -unix-socket string
        Connect over a unix socket. This overrides the host address in target URLs
  -workers uint
        Initial number of workers (default 10)

encode command:
  -output string
        Output file (default "stdout")
  -to string
        Output encoding [csv, gob, json] (default "json")

plot command:
  -output string
        Output file (default "stdout")
  -threshold int
        Threshold of data points above which series are downsampled. (default 4000)
  -title string
        Title and header of the resulting HTML page (default "Vegeta Plot")

report command:
  -buckets string
        Histogram buckets, e.g.: "[0,1ms,10ms]"
  -every duration
        Report interval
  -output string
        Output file (default "stdout")
  -type string
        Report type to generate [text, json, hist[buckets], hdrplot] (default "text")

examples:
  echo "GET http://localhost/" | vegeta attack -duration=5s | tee results.bin | vegeta report
  vegeta report -type=json results.bin > metrics.json
  cat results.bin | vegeta plot > plot.html
  cat results.bin | vegeta report -type="hist[0,100ms,200ms,300ms]"

-cpus

Specifies the number of CPUs to be used internally. It defaults to the amount of CPUs available in the system.

-profile

Specifies which profiler to enable during execution. Both cpu and heap profiles are supported. It defaults to none.

-version

Prints the version and exits.

attack command

-body

Specifies the file whose content will be set as the body of every request unless overridden per attack target, see -targets.

-cert

Specifies the PEM encoded TLS client certificate file to be used with HTTPS requests. If -key isn't specified, it will be set to the value of this flag.

-chunked

Specifies whether to send request bodies with the chunked transfer encoding.

-connections

Specifies the maximum number of idle open connections per target host.

-dns-ttl

Specifies the duration to cache DNS lookups for. A zero value caches forever. A negative value disables caching altogether.

-max-connections

Specifies the maximum number of connections per target host.

-duration

Specifies the amount of time to issue request to the targets. The internal concurrency structure's setup has this value as a variable. The actual run time of the test can be longer than specified due to the responses delay. Use 0 for an infinite attack.

-format

Specifies the targets format to decode.

json format

The JSON format makes integration with programs that produce targets dynamically easier. Each target is one JSON object in its own line. The method and url fields are required. If present, the body field must be base64 encoded. The generated JSON Schema defines the format in detail.

jq -ncM '{method: "GET", url: "http://goku", body: "Punch!" | @base64, header: {"Content-Type": ["text/plain"]}}' |
  vegeta attack -format=json -rate=100 | vegeta encode

http format

The http format almost resembles the plain-text HTTP message format defined in RFC 2616 but it doesn't support in-line HTTP bodies, only references to files that are loaded and used as request bodies (as exemplified below).

Although targets in this format can be produced by other programs, it was originally meant to be used by people writing targets by hand for simple use cases.

Here are a few examples of valid targets files in the http format:

Simple targets

GET http://goku:9090/path/to/dragon?item=ball
GET http://user:password@goku:9090/path/to
HEAD http://goku:9090/path/to/success

Targets with custom headers

GET http://user:password@goku:9090/path/to
X-Account-ID: 8675309

DELETE http://goku:9090/path/to/remove
Confirmation-Token: 90215
Authorization: Token DEADBEEF

Targets with custom bodies

POST http://goku:9090/things
@/path/to/newthing.json

PATCH http://goku:9090/thing/71988591
@/path/to/thing-71988591.json

Targets with custom bodies and headers

POST http://goku:9090/things
X-Account-ID: 99
@/path/to/newthing.json

Add comments

Lines starting with # are ignored.

# get a dragon ball
GET http://goku:9090/path/to/dragon?item=ball
# specify a test account
X-Account-ID: 99

-h2c

Specifies that HTTP2 requests are to be sent over TCP without TLS encryption.

-header

Specifies a request header to be used in all targets defined, see -targets. You can specify as many as needed by repeating the flag.

-http2

Specifies whether to enable HTTP/2 requests to servers which support it.

-insecure

Specifies whether to ignore invalid server TLS certificates.

-keepalive

Specifies whether to reuse TCP connections between HTTP requests.

-key

Specifies the PEM encoded TLS client certificate private key file to be used with HTTPS requests.

-laddr

Specifies the local IP address to be used.

-lazy

Specifies whether to read the input targets lazily instead of eagerly. This allows streaming targets into the attack command and reduces memory footprint. The trade-off is one of added latency in each hit against the targets.

-max-body

Specifies the maximum number of bytes to capture from the body of each response. Remaining unread bytes will be fully read but discarded. Set to -1 for no limit. It knows how to interpret values like these:

• "10 MB" -> 10MB
• "10240 g" -> 10TB
• "2000" -> 2000B
• "1tB" -> 1TB
• "5 peta" -> 5PB
• "28 kilobytes" -> 28KB
• "1 gigabyte" -> 1GB

-name

Specifies the name of the attack to be recorded in responses.

-output

Specifies the output file to which the binary results will be written to. Made to be piped to the report command input. Defaults to stdout.

-rate

Specifies the request rate per time unit to issue against the targets. The actual request rate can vary slightly due to things like garbage collection, but overall it should stay very close to the specified. If no time unit is provided, 1s is used.

A -rate of 0 or infinity means vegeta will send requests as fast as possible. Use together with -max-workers to model a fixed set of concurrent users sending requests serially (i.e. waiting for a response before sending the next request).

Setting -max-workers to a very high number while setting -rate=0 can result in vegeta consuming too many resources and crashing. Use with care.

-redirects

Specifies the max number of redirects followed on each request. The default is 10. When the value is -1, redirects are not followed but the response is marked as successful.

-resolvers

Specifies custom DNS resolver addresses to use for name resolution instead of the ones configured by the operating system. Works only on non Windows systems.

-root-certs

Specifies the trusted TLS root CAs certificate files as a comma separated list. If unspecified, the default system CAs certificates will be used.

-session-tickets

Specifies whether to support TLS session resumption using session tickets.

-targets

Specifies the file from which to read targets, defaulting to stdin. See the -format section to learn about the different target formats.

-timeout

Specifies the timeout for each request. A value of 0 disables timeouts.

-workers

Specifies the initial number of workers used in the attack. The actual number of workers will increase if necessary in order to sustain the requested rate, unless it'd go beyond -max-workers.

-max-workers

Specifies the maximum number of workers used in the attack. It can be used to control the concurrency level used by an attack.

report command

```console Usage: vegeta report [options] [...]

Outputs a report of attack results.

Arguments: A file with vegeta attack results encoded with one of the supported encodings (gob | json | csv) [default: stdin]

Options: --type Which report type to generate (text | json | hist[buckets] | hdrplot). [default: text]

--buckets Histogram buckets, e.g.: '[0,1ms,10ms]'

--every Write the report to --output at every given interval (e.g 100ms) The default of 0 means the report will only be written after all results have been processed. [default: 0]

--output Output file [default: stdout]

Examples: echo "GET http://:80" | vegeta attack -rate=10/s > results.gob echo "GET http://: