h2load - HTTP/2 benchmarking tool
h2load [OPTIONS]... [URI]...
benchmarking tool for HTTP/2 server
- <URI>
- Specify URI to access. Multiple URIs can be specified. URIs are used in
this order for each client. All URIs are used, then first URI is used and
then 2nd URI, and so on. The scheme, host and port in the subsequent URIs,
if present, are ignored. Those in the first URI are used solely.
Definition of a base URI overrides all scheme, host or port values.
- -n,
--requests=<N>
- Number of requests across all clients. If it is used with
--timing-script-file option, this option specifies the number of
requests each client performs rather than the number of requests across
all clients. This option is ignored if timing-based benchmarking is
enabled (see --duration option).
Default: 1
- -c,
--clients=<N>
- Number of concurrent clients. With -r option, this specifies the
maximum number of connections to be made.
Default: 1
- -i,
--input-file=<PATH>
- Path of a file with multiple URIs are separated by EOLs. This option will
disable URIs getting from command-line. If '-' is given as <PATH>,
URIs will be read from stdin. URIs are used in this order for each client.
All URIs are used, then first URI is used and then 2nd URI, and so on. The
scheme, host and port in the subsequent URIs, if present, are ignored.
Those in the first URI are used solely. Definition of a base URI overrides
all scheme, host or port values.
- -m,
--max-concurrent-streams=<N>
- Max concurrent streams to issue per session. When http/1.1 is used, this
specifies the number of HTTP pipelining requests in-flight.
Default: 1
- -w,
--window-bits=<N>
- Sets the stream level initial window size to (2**<N>)-1. For QUIC,
<N> is capped to 26 (roughly 64MiB).
Default: 30
- --ciphers=<SUITE>
- Set allowed cipher list for TLSv1.2 or earlier. The format of the string
is described in OpenSSL ciphers(1).
Default:
ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
- --tls13-ciphers=<SUITE>
- Set allowed cipher list for TLSv1.3. The format of the string is described
in OpenSSL ciphers(1).
Default:
TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256
- -p,
--no-tls-proto=<PROTOID>
- Specify ALPN identifier of the protocol to be used when accessing http URI
without SSL/TLS. Available protocols: h2c and http/1.1
Default: h2c
- -d,
--data=<PATH>
- Post FILE to server. The request method is changed to POST. For http/1.1
connection, if -d is used, the maximum number of in-flight
pipelined requests is set to 1.
- -r,
--rate=<N>
- Specifies the fixed rate at which connections are created. The rate must
be a positive integer, representing the number of connections to be made
per rate period. The maximum number of connections to be made is given in
-c option. This rate will be distributed among threads as evenly as
possible. For example, with -t2 and -r4, each thread gets 2
connections per period. When the rate is 0, the program will run as it
normally does, creating connections at whatever variable rate it wants.
The default value for this option is 0. -r and -D are
mutually exclusive.
- --rate-period=<DURATION>
- Specifies the time period between creating connections. The period must be
a positive number, representing the length of the period in time. This
option is ignored if the rate option is not used. The default value for
this option is 1s.
- -D,
--duration=<DURATION>
- Specifies the main duration for the measurements in case of timing-based
benchmarking. -D and -r are mutually exclusive.
- --warm-up-time=<DURATION>
- Specifies the time period before starting the actual measurements, in case
of timing-based benchmarking. Needs to provided along with -D
option.
- -T,
--connection-active-timeout=<DURATION>
- Specifies the maximum time that h2load is willing to keep a connection
open, regardless of the activity on said connection. <DURATION> must
be a positive integer, specifying the amount of time to wait. When no
timeout value is set (either active or inactive), h2load will keep a
connection open indefinitely, waiting for a response.
- -N,
--connection-inactivity-timeout=<DURATION>
- Specifies the amount of time that h2load is willing to wait to see
activity on a given connection. <DURATION> must be a positive
integer, specifying the amount of time to wait. When no timeout value is
set (either active or inactive), h2load will keep a connection open
indefinitely, waiting for a response.
- --timing-script-file=<PATH>
- Path of a file containing one or more lines separated by EOLs. Each script
line is composed of two tab-separated fields. The first field represents
the time offset from the start of execution, expressed as a positive value
of milliseconds with microsecond resolution. The second field represents
the URI. This option will disable URIs getting from command-line. If '-'
is given as <PATH>, script lines will be read from stdin. Script
lines are used in order for each client. If -n is given, it must be
less than or equal to the number of script lines, larger values are
clamped to the number of script lines. If -n is not given, the
number of requests will default to the number of script lines. The scheme,
host and port defined in the first URI are used solely. Values contained
in other URIs, if present, are ignored. Definition of a base URI overrides
all scheme, host or port values. --timing-script-file and
--rps are mutually exclusive.
- -B,
--base-uri=(<URI>|unix:<PATH>)
- Specify URI from which the scheme, host and port will be used for all
requests. The base URI overrides all values defined either at the command
line or inside input files. If argument starts with "unix:",
then the rest of the argument will be treated as UNIX domain socket path.
The connection is made through that path instead of TCP. In this case,
scheme is inferred from the first URI appeared in the command line or
inside input files as usual.
- --npn-list=<LIST>
- Comma delimited list of ALPN protocol identifier sorted in the order of
preference. That means most desirable protocol comes first. This is used
in both ALPN and NPN. The parameter must be delimited by a single comma
only and any white spaces are treated as a part of protocol string.
Default: h2,h2-16,h2-14,http/1.1
- --h1
- Short hand for --npn-list=http/1.1 --no-tls-proto=http/1.1,
which effectively force http/1.1 for both http and https URI.
- Specify decoder header table size.
Default: 4K
- --encoder-header-table-size=<SIZE>
- Specify encoder header table size. The decoder (server) specifies the
maximum dynamic table size it accepts. Then the negotiated dynamic table
size is the minimum of this option value and the value which server
specified.
Default: 4K
- --log-file=<PATH>
- Write per-request information to a file as tab-separated columns: start
time as microseconds since epoch; HTTP status code; microseconds until end
of response. More columns may be added later. Rows are ordered by end-of-
response time when using one worker thread, but may appear slightly out of
order with multiple threads due to buffering. Status code is -1 for failed
streams.
- --qlog-file-base=<PATH>
- Enable qlog output and specify base file name for qlogs. Qlog is emitted
for each connection. For a given base name "base", each output
file name becomes "base.M.N.sqlog" where M is worker ID and N is
client ID (e.g. "base.0.3.sqlog"). Only effective in QUIC
runs.
- --rps=<N>
- Specify request per second for each client. --rps and
--timing-script-file are mutually exclusive.
- --max-udp-payload-size=<SIZE>
- Specify the maximum outgoing UDP datagram payload size.
- --version
- Display version information and exit.
The <SIZE> argument is an integer and an optional unit
(e.g., 10K is 10 * 1024). Units are K, M and G (powers of 1024).
The <DURATION> argument is an integer and an optional unit
(e.g., 1s is 1 second and 500ms is 500 milliseconds). Units are h, m, s or
ms (hours, minutes, seconds and milliseconds, respectively). If a unit is
omitted, a second is used as unit.
- requests
- total
- The number of requests h2load was instructed to make.
- started
- The number of requests h2load has started.
- done
- The number of requests completed.
- succeeded
- The number of requests completed successfully. Only HTTP status code 2xx
or3xx are considered as success.
- failed
- The number of requests failed, including HTTP level failures
(non-successful HTTP status code).
- errored
- The number of requests failed, except for HTTP level failures. This is the
subset of the number reported in failed and most likely the network
level failures or stream was reset by RST_STREAM.
- timeout
- The number of requests whose connection timed out before they were
completed. This is the subset of the number reported in
errored.
- status
codes
- The number of status code h2load received.
- traffic
- total
- The number of bytes received from the server "on the wire". If
requests were made via TLS, this value is the number of decrypted
bytes.
- The number of response header bytes from the server without decompression.
The space savings shows efficiency of header compression. Let
decompressed(headers) to the number of bytes used for header fields
after decompression. The space savings is calculated by (1 -
headers / decompressed(headers)) * 100. For HTTP/1.1, this
is usually 0.00%, since it does not have header compression. For HTTP/2,
it shows some insightful numbers.
- data
- The number of response body bytes received from the server.
- time for
request
- min
- The minimum time taken for request and response.
- max
- The maximum time taken for request and response.
- mean
- The mean time taken for request and response.
- sd
- The standard deviation of the time taken for request and response.
- +/- sd
- The fraction of the number of requests within standard deviation range
(mean +/- sd) against total number of successful requests.
- time for
connect
- min
- The minimum time taken to connect to a server including TLS
handshake.
- max
- The maximum time taken to connect to a server including TLS
handshake.
- mean
- The mean time taken to connect to a server including TLS handshake.
- sd
- The standard deviation of the time taken to connect to a server.
- +/- sd
- The fraction of the number of connections within standard deviation range
(mean +/- sd) against total number of successful connections.
- time for 1st byte (of
(decrypted in case of TLS) application data)
- min
- The minimum time taken to get 1st byte from a server.
- max
- The maximum time taken to get 1st byte from a server.
- mean
- The mean time taken to get 1st byte from a server.
- sd
- The standard deviation of the time taken to get 1st byte from a
server.
- +/- sd
- The fraction of the number of connections within standard deviation range
(mean +/- sd) against total number of successful connections.
- req/s
- min
- The minimum request per second among all clients.
- max
- The maximum request per second among all clients.
- mean
- The mean request per second among all clients.
- sd
- The standard deviation of request per second among all clients.
server.
- +/- sd
- The fraction of the number of connections within standard deviation range
(mean +/- sd) against total number of successful connections.
h2load sets large flow control window by default, and effectively
disables flow control to avoid under utilization of server performance. To
set smaller flow control window, use -w and -W options. For
example, use -w16 -W16 to set default window size described in HTTP/2
protocol specification.
2012, 2015, 2016, Tatsuhiro Tsujikawa