vegeta Documentation

File: README.md Copy Chapter

Vegeta [](https://github.com/tsenart/vegeta/actions) [](https://goreportcard.com/report/github.com/tsenart/vegeta) [](https://pkg.go.dev/github.com/tsenart/vegeta/v12/lib) [](https://gitter.im/tsenart/vegeta?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [](#donate)

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 Copy Chapter

• 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 Copy Chapter

Pre-compiled executables Copy Section

Get them here.

macOS Copy Section

You can install Vegeta using the Homebrew:

$ brew update && brew install vegeta

Or with MacPorts:

$ port install vegeta

Arch Linux Copy Section

$ pacman -S vegeta

FreeBSD Copy Section

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

$ pkg install vegeta

Source Copy Section

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

Versioning Copy Chapter

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 Copy Chapter

See CONTRIBUTING.md.

Usage manual Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

`-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 Copy Section

`-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 Copy Section

Usage: vegeta report [options] [<file>...]

Outputs a report of attack results.

Arguments:
  <file>  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://:80" | vegeta attack -rate=100/s | vegeta encode > results.json
  vegeta report results.*

`report -type=text`

Requests      [total, rate, throughput] 1200, 120.00, 65.87
Duration      [total, attack, wait]     10.094965987s, 9.949883921s, 145.082066ms
Latencies     [min, mean, 50, 95, 99, max]  90.438129ms, 113.172398ms, 108.272568ms, 140.18235ms, 247.771566ms, 264.815246ms
Bytes In      [total, mean]             3714690, 3095.57
Bytes Out     [total, mean]             0, 0.00
Success       [ratio]                   55.42%
Status Codes  [code:count]              0:535  200:665
Error Set:
Get http://localhost:6060: dial tcp 127.0.0.1:6060: connection refused
Get http://localhost:6060: read tcp 127.0.0.1:6060: connection reset by peer
Get http://localhost:6060: dial tcp 127.0.0.1:6060: connection reset by peer
Get http://localhost:6060: write tcp 127.0.0.1:6060: broken pipe
Get http://localhost:6060: net/http: transport closed before response was received
Get http://localhost:6060: http: can't write HTTP request on broken connection

The Requests row shows:

• The total number of issued requests.
• The real request rate sustained during the attack period.
• The throughput of successful requests over the total period.

The Duration row shows:

• The attack time taken issuing all requests (total - wait)
• The wait time waiting for the response to the last issued request (total - attack)
• The total time taken in the attack (attack + wait)

Latency is the amount of time taken for a response to a request to be read (including the -max-body bytes from the response body).

• min is the minimum latency of all requests in an attack.
• mean is the arithmetic mean / average of the latencies of all requests in an attack.
• 50, 90, 95, 99 are the 50th, 90th, 95th and 99th percentiles, respectively, of the latencies of all requests in an attack. To understand more about why these are useful, I recommend this article from @tylertreat.
• max is the maximum latency of all requests in an attack.

The Bytes In and Bytes Out rows shows:

• The total number of bytes sent (out) or received (in) with the request or response bodies.
• The mean number of bytes sent (out) or received (in) with the request or response bodies.

The Success ratio shows the percentage of requests whose responses didn't error and had status codes between 200 and 400 (non-inclusive).

The Status Codes row shows a histogram of status codes. 0 status codes mean a request failed to be sent.

The Error Set shows a unique set of errors returned by all issued requests. These include requests that got non-successful response status code.

`report -type=json`

All duration like fields are in nanoseconds.

{
  "latencies": {
    "total": 237119463,
    "mean": 2371194,
    "50th": 2854306,
    "90th": 3228223,
    "95th": 3478629,
    "99th": 3530000,
    "max": 3660505,
    "min": 1949582
  },
  "buckets": {
    "0": 9952,
    "1000000": 40,
    "2000000": 6,
    "3000000": 0,
    "4000000": 0,
    "5000000": 2
  },
  "bytes_in": {
    "total": 606700,
    "mean": 6067
  },
  "bytes_out": {
    "total": 0,
    "mean": 0
  },
  "earliest": "2015-09-19T14:45:50.645818631+02:00",
  "latest": "2015-09-19T14:45:51.635818575+02:00",
  "end": "2015-09-19T14:45:51.639325797+02:00",
  "duration": 989999944,
  "wait": 3507222,
  "requests": 100,
  "rate": 101.01010672380401,
  "throughput": 101.00012489812,
  "success": 1,
  "status_codes": {
    "200": 100
  },
  "errors": []
}

In the buckets field, each key is a nanosecond value representing the lower bound of a bucket.
The upper bound is implied by the next higher bucket.
Upper bounds are non-inclusive.
The highest bucket is the overflow bucket; it has no upper bound.
The values are counts of how many requests fell into that particular bucket.
If the -buckets parameter is not present, the buckets field is omitted.

`report -type=hist`

Computes and prints a text based histogram for the given buckets.
Each bucket upper bound is non-inclusive.

cat results.bin | vegeta report -type='hist[0,2ms,4ms,6ms]'
Bucket         #     %       Histogram
[0,     2ms]   6007  32.65%  ########################
[2ms,   4ms]   5505  29.92%  ######################
[4ms,   6ms]   2117  11.51%  ########
[6ms,   +Inf]  4771  25.93%  ###################

`report -type=hdrplot`

Writes out results in a format plottable by https://hdrhistogram.github.io/HdrHistogram/plotFiles.html.

/* Detailed source-code truncated for AI context efficiency. */

`encode` command Copy Section

Usage: vegeta encode [options] [<file>...]

Encodes vegeta attack results from one encoding to another.
The supported encodings are Gob (binary), CSV and JSON.
Each input file may have a different encoding which is detected
automatically.

The CSV encoder doesn't write a header. The columns written by it are:

  1. Unix timestamp in nanoseconds since epoch
  2. HTTP status code
  3. Request latency in nanoseconds
  4. Bytes out
  5. Bytes in
  6. Error
  7. Base64 encoded response body
  8. Attack name
  9. Sequence number of request
  10. Method
  11. URL
  12. Base64 encoded response headers

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

Options:
  --to      Output encoding (gob | json | csv) [default: json]
  --output  Output file [default: stdout]

Examples:
  echo "GET http://:80" | vegeta attack -rate=1/s > results.gob
  cat results.gob | vegeta encode | jq -c 'del(.body)' | vegeta encode -to gob

`plot` command Copy Section

Usage: vegeta plot [options] [<file>...]

Outputs an HTML time series plot of request latencies over time.
The X axis represents elapsed time in seconds from the beginning
of the earliest attack in all input files. The Y axis represents
request latency in milliseconds.

Click and drag to select a region to zoom into. Double click to zoom out.
Choose a different number on the bottom left corner input field
to change the moving average window size (in data points).

Arguments:
  <file>  A file output by running vegeta attack [default: stdin]

Options:
  --title      Title and header of the resulting HTML page.
               [default: Vegeta Plot]
  --threshold  Threshold of data points to downsample series to.
               Series with less than --threshold number of data
               points are not downsampled. [default: 4000]

Examples:
  echo "GET http://:80" | vegeta attack -name=50qps -rate=50 -duration=5s > results.50qps.bin
  cat results.50qps.bin | vegeta plot > plot.50qps.html
  echo "GET http://:80" | vegeta attack -name=100qps -rate=100 -duration=5s > results.100qps.bin
  vegeta plot results.50qps.bin results.100qps.bin > plot.html

Usage: Generated targets Copy Chapter

Apart from accepting a static list of targets, Vegeta can be used together with another program that generates them in a streaming fashion. Here's an example of that using the jq utility that generates targets with an incrementing id in their body.

jq -ncM 'while(true; .+1) | {method: "POST", url: "http://:6060", body: {id: .} | @base64 }' | \
  vegeta attack -rate=50/s -lazy -format=json -duration=30s | \
  tee results.bin | \
  vegeta report

Usage: Distributed attacks Copy Chapter

Whenever your load test can't be conducted due to Vegeta hitting machine limits
such as open files, memory, CPU or network bandwidth, it's a good idea to use Vegeta in a distributed manner.

In a hypothetical scenario where the desired attack rate is 60k requests per second,
let's assume we have 3 machines with vegeta installed.

Make sure open file descriptor and process limits are set to a high number for your user on each machine
using the ulimit command.

We're ready to start the attack. All we need to do is to divide the intended rate by the number of machines,
and use that number on each attack. Here we'll use pdsh for orchestration.

$ PDSH_RCMD_TYPE=ssh pdsh -b -w '10.0.1.1,10.0.2.1,10.0.3.1' \
    'echo "GET http://target/" | vegeta attack -rate=20000 -duration=60s > result.bin'

After the previous command finishes, we can gather the result files to use on our report.

$ for machine in 10.0.1.1 10.0.2.1 10.0.3.1; do
    scp $machine:~/result.bin $machine.bin &
  done

The report command accepts multiple result files.
It'll read and sort them by timestamp before generating reports.

vegeta report *.bin

Another way to gather results in distributed tests is to use the built-in Prometheus Exporter and configure a Prometheus Server to get test results from all Vegeta instances. See attack option "prometheus-addr" for more details and a complete example in the section "Prometheus Support".

Usage: Real-time Analysis Copy Chapter

If you are a happy user of iTerm, you can integrate vegeta with jplot using jaggr to plot a vegeta report in real-time in the comfort of your terminal:

echo 'GET http://localhost:8080' | \
    vegeta attack -rate 5000 -duration 10m | vegeta encode | \
    jaggr @count=rps \
          hist\[100,200,300,400,500\]:code \
          p25,p50,p95:latency \
          sum:bytes_in \
          sum:bytes_out | \
    jplot rps+code.hist.100+code.hist.200+code.hist.300+code.hist.400+code.hist.500 \
          latency.p95+latency.p50+latency.p25 \
          bytes_in.sum+bytes_out.sum

Usage: Library Copy Chapter

The library versioning follows SemVer v2.0.0.
Since lib/v9.0.0, the library and cli
are versioned separately to better isolate breaking changes to each component.

See Versioning for more details on git tag naming schemes and compatibility
with go mod.

package main

import (
  "fmt"
  "time"

  vegeta "github.com/tsenart/vegeta/v12/lib"
)

func main() {
  rate := vegeta.Rate{Freq: 100, Per: time.Second}
  duration := 4 * time.Second
  targeter := vegeta.NewStaticTargeter(vegeta.Target{
    Method: "GET",
    URL:    "http://localhost:9100/",
  })
  attacker := vegeta.NewAttacker()

  var metrics vegeta.Metrics
  for res := range attacker.Attack(targeter, rate, duration, "Big Bang!") {
    metrics.Add(res)
  }
  metrics.Close()

  fmt.Printf("99th percentile: %s\n", metrics.Latencies.P99)
}

Limitations

There will be an upper bound of the supported rate which varies on the
machine being used.
You could be CPU bound (unlikely), memory bound (more likely) or
have system resource limits being reached which ought to be tuned for
the process execution. The important limits for us are file descriptors
and processes. On a UNIX system you can get and set the current
soft-limit values for a user.

$ ulimit -n # file descriptors
2560
$ ulimit -u # processes / threads
709

Just pass a new number as the argument to change it.

Prometheus support Copy Chapter

Vegeta has a built-in Prometheus Exporter that may be enabled during attacks so that you can point any Prometheus instance to Vegeta attack processes and monitor attack metrics.

To enable the Prometheus Exporter on the command line, set the "prometheus-addr" flag.

A Prometheus HTTP endpoint will be available only during the lifespan of an attack and will be closed right after the attack is finished.

The following metrics are exposed:

• request_bytes_in - bytes count received from targeted servers by "url", "method" and "status"
• request_bytes_out - bytes count sent to targeted server by "url", "method" and "status"
• request_seconds - histogram with request latency and counters by "url", "method" and "status"
• request_fail_count - count of failed requests by "url", "method", "status" and "message"

Check file lib/prom/grafana.json with the source of this sample dashboard in Grafana.

Limitations Copy Section

1. Prometheus scrapes metrics from a running vegeta attack process and assigns timestamps to samples on its server. This means result timestamps aren't accurate (i.e. they're scraping time, not result time).
2. Configuring Prometheus to scrape vegeta needs to happen out-of-band. That's a hassle!
3. Since there's no coordination between a vegeta attack process and a Prometheus server, an attack process will finish before Prometheus has the chance to scrape the latest observations.

Why aren't we using pushgateway instead? See this comment.

There's an issue tracking the proper solution to all these limitations which is a remote write integration.

License Copy Chapter

See LICENSE.

Donate Copy Chapter

If you use and love Vegeta, please consider sending some Satoshi to
1MDmKC51ve7Upxt75KoNM6x1qdXHFK6iW2. In case you want to be mentioned as a
sponsor, let me know!

File: scripts/load-ramping/README.md Copy Chapter

Load ramping

This script will automatically run vegeta against a target with different request
rates and graph the latency distribution and success rate at each request rate.

Usage:

echo GET http://localhost:8080/ | python3 ramp-requests.py

Dependencies:

• Python 3
• Gnuplot

For more documentation, see https://github.com/tsenart/vegeta/wiki/Load-ramping