h2load man page

h2load — HTTP/2 benchmarking tool

Synopsis

h2load [Options]... [URI]...

Description

benchmarking tool for HTTP/2 and SPDY 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.

Options

-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

-t, --threads=<N>

Number of native threads.

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 SPDY, 2**<N> is used instead.

Default: 30

-W, --connection-window-bits=<N>

Sets  the  connection  level   initial  window  size  to (2**<N>)-1.  For SPDY, if <N>  is strictly less than 16, this option  is ignored.   Otherwise 2**<N> is  used for SPDY.

Default: 30

-H, --header=<HEADER>

Add/Override a header to the requests.

--ciphers=<SUITE>

Set allowed  cipher list.  The  format of the  string is described in OpenSSL ciphers(1).

Default: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-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.

--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=<N>

Specifies the main duration for the measurements in case of timing-based benchmarking.

--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.

-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.

--header-table-size=<SIZE>

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

-v, --verbose

Output debug information.

--version

Display version information and exit.

-h, --help

Display this help 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.

Output

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.

headers

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 and SPDY, 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.

max

The maximum time taken to connect to a server.

mean

The mean time taken to connect to a server.

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.

Flow Control

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 and SPDY protocol specification.

See Also

nghttp(1), nghttpd(1), nghttpx(1)

Author

Tatsuhiro Tsujikawa

Referenced By

nghttp(1), nghttpd(1), nghttpx(1).

Sep 20, 2017 1.26.0 nghttp2