← Full reference

ab (Apache Bench)

Load-test an HTTP server — request count, concurrency, keep-alive and how to read the report

ab (ApacheBench, package apache2-utils) sends a given number of HTTP requests to a single URL, several at a time, and prints a report: how many requests per second the server handled, how many failed and how response times were distributed. Good for a quick "before and after" on one URL; it can't do multi-page scenarios.

Syntax

ab [options] http://host[:port]/path

The path is required: http://127.0.0.1:8080 without a trailing / gives an invalid URL error.

Options

Volume and concurrency

OptionWhat it does
-n Ntotal number of requests (default 1)
-c Nhow many requests to keep in flight at once (default 1); can't exceed -n
-t secrun for at most this many seconds; implies -n 50000
-kkeep-alive: reuse connections instead of a new TCP connection per request
-s sechow long to wait for each response (default 30)
-rdon't abort the test on socket receive errors

Request

OptionWhat it does
-m METHODcustom method
-iHEAD instead of GET
-p filePOST with the body from a file; set -T along with it
-u filePUT with the body from a file
-T typeContent-Type for -p / -u (default text/plain)
-H 'Name: value'add a header; can be repeated
-C 'name=value'add a cookie
-A user:passwordBasic authentication
-X proxy:portgo through a proxy

Report

OptionWhat it does
-qdon't print Completed 100 requests progress
-ldon't count varying response lengths as errors (for dynamic pages)
-ddon't print the percentile table
-Sdon't print standard deviations
-e file.csvpercentiles as CSV
-g file.tsvall measurements in gnuplot format
-v Ndebug verbosity: 2 and up prints headers

Reading the report

Concurrency Level:      10
Time taken for tests:   0.018 seconds
Complete requests:      200
Failed requests:        0
Non-2xx responses:      20
Keep-Alive requests:    100
Requests per second:    10897.40 [#/sec] (mean)
Time per request:       0.918 [ms] (mean)
Time per request:       0.092 [ms] (mean, across all concurrent requests)
Transfer rate:          2596.65 [Kbytes/sec] received
LineMeaning
Document Lengthbody size of the first response; "length errors" are counted against it
Complete requestshow many requests got a response
Failed requestsfailures: in parentheses Connect, Receive, Length (body of a different length), Exceptions
Non-2xx responsesresponses with a non-2xx code — not included in Failed (the line only appears if there were any)
Keep-Alive requestshow many requests went over already-open connections (only with -k)
Requests per secondthroughput — the headline number
Time per request (first)mean time of one request as seen by the client
Time per request (across all)the first one divided by -c — essentially 1/RPS
Connection TimesConnect — TCP setup, Waiting — until the first response byte, Processing — from connection to the end of the response, Total — overall
Percentage … served withinpercentiles: 95% 4 — 95 % of requests completed within 4 ms; 100% — the slowest

Exit codes

0 — the test ran (even if there were Failed and Non-2xx!); non-zero — the test couldn't be run: bad URL, bad options, server unreachable.

Examples

# 1000 requests, 50 at a time
ab -n 1000 -c 50 http://127.0.0.1:8080/

# same with keep-alive — usually several times faster
ab -k -n 1000 -c 50 http://127.0.0.1:8080/

# run for 10 seconds without progress and pick out the key lines
ab -q -t 10 -c 20 http://127.0.0.1:8080/ | grep -E 'Requests per second|Failed|Non-2xx|95%'

# POST with the body from a file
echo 'name=demo' > body.txt
ab -n 100 -c 10 -p body.txt -T application/x-www-form-urlencoded http://127.0.0.1:8080/api/form

# page behind Basic auth, custom header
ab -n 200 -c 10 -A admin:secret -H 'Accept: application/json' http://127.0.0.1:8080/private/

# dynamic page with varying response length
ab -l -n 500 -c 20 http://127.0.0.1:8080/dynamic

# percentiles as CSV for a chart
ab -n 1000 -c 20 -e percentiles.csv http://127.0.0.1:8080/ >/dev/null

Pitfalls

  • 404 and 500 are not Failed. Error responses count as "successful" requests and land in the Non-2xx responses line. A high RPS with nothing but 404s means nothing — always check that line. The ab exit code is still 0 in this case.
  • Failed requests with Length on a dynamic page is not a server error: the body just has a different length each time. Add -l.
  • Without a trailing / in the URL ab fails right away with invalid URL: http://127.0.0.1:8080/, not http://127.0.0.1:8080.
  • -c greater than -n is not allowed — Cannot use concurrency level greater than total number of requests.
  • Without -k every request is a new TCP connection. The numbers come out noticeably worse than for a browser, which keeps connections open.
  • ab uses CPU itself. If it runs on the same machine as the server, they share the CPU and the result is understated.
  • -p to a static file in nginx returns 405 — everything ends up in Non-2xx.
  • One URL is not real load. The cache serves the same page over and over; real users hit different addresses.

See also

curl · wget · nginx · htpasswd · top