3 h2load - HTTP/2 benchmarking tool - HOW-TO
4 ==========================================
6 :doc:`h2load.1` is benchmarking tool for HTTP/2 and HTTP/1.1. It
7 supports SSL/TLS and clear text for all supported protocols.
12 h2load is compiled alongside nghttp2 and requires that the
13 ``--enable-app`` flag is passed to ``./configure`` and `required
14 dependencies <https://github.com/nghttp2/nghttp2#requirements>`_ are
15 available during compilation. For details on compiling, see `nghttp2:
17 <https://github.com/nghttp2/nghttp2#building-from-git>`_.
22 In order to set benchmark settings, specify following 3 options.
25 The number of total requests. Default: 1
28 The number of concurrent clients. Default: 1
31 The max concurrent streams to issue per client. Default: 1
33 For SSL/TLS connection, the protocol will be negotiated via ALPN/NPN.
34 You can set specific protocols in :option:`--npn-list` option. For
35 cleartext connection, the default protocol is HTTP/2. To change the
36 protocol in cleartext connection, use :option:`--no-tls-proto` option.
37 For convenience, :option:`--h1` option forces HTTP/1.1 for both
38 cleartext and SSL/TLS connections.
40 Here is a command-line to perform benchmark to URI \https://localhost
41 using total 100000 requests, 100 concurrent clients and 10 max
46 $ h2load -n100000 -c100 -m10 https://localhost
48 The benchmarking result looks like this:
52 finished in 7.08s, 141164.80 req/s, 555.33MB/s
53 requests: 1000000 total, 1000000 started, 1000000 done, 1000000 succeeded, 0 failed, 0 errored, 0 timeout
54 status codes: 1000000 2xx, 0 3xx, 0 4xx, 0 5xx
55 traffic: 4125025824 bytes total, 11023424 bytes headers (space savings 93.07%), 4096000000 bytes data
56 min max mean sd +/- sd
57 time for request: 15.31ms 146.85ms 69.78ms 9.26ms 92.43%
58 time for connect: 1.08ms 25.04ms 10.71ms 9.80ms 64.00%
59 time to 1st byte: 25.36ms 184.96ms 79.11ms 53.97ms 78.00%
60 req/s (client) : 1412.04 1447.84 1426.52 10.57 63.00%
62 See the h2load manual page :ref:`h2load-1-output` section for the
63 explanation of the above numbers.
65 Timing-based load-testing
66 -------------------------
68 As of v1.26.0, h2load supports timing-based load-testing. This method
69 performs load-testing in terms of a given duration instead of a
70 pre-defined number of requests. The new option :option:`--duration`
71 specifies how long the load-testing takes. For example,
72 ``--duration=10`` makes h2load perform load-testing against a server
73 for 10 seconds. You can also specify a “warming-up” period with
74 :option:`--warm-up-time`. If :option:`--duration` is used,
75 :option:`-n` option is ignored.
77 The following command performs load-testing for 10 seconds after 5
78 seconds warming up period:
82 $ h2load -c100 -m100 --duration=10 --warm-up-time=5 https://localhost
87 HTTP/2 has flow control and it may affect benchmarking results. By
88 default, h2load uses large enough flow control window, which
89 effectively disables flow control. To adjust receiver flow control
90 window size, there are following options:
93 Sets the stream level initial window size to
97 Sets the connection level initial window size to
103 Sometimes benchmarking client itself becomes a bottleneck. To remedy
104 this situation, use :option:`-t` option to specify the number of native
108 The number of native threads. Default: 1
110 Selecting protocol for clear text
111 ---------------------------------
113 By default, if \http:// URI is given, HTTP/2 protocol is used. To
114 change the protocol to use for clear text, use :option:`-p` option.
119 If multiple URIs are specified, they are used in round robin manner.
123 Please note that h2load uses scheme, host and port in the first URI
124 and ignores those parts in the rest of the URIs.
129 To request against UNIX domain socket, use :option:`--base-uri`, and
130 specify ``unix:`` followed by the path to UNIX domain socket. For
131 example, if UNIX domain socket is ``/tmp/nghttpx.sock``, use
132 ``--base-uri=unix:/tmp/nghttpx.sock``. h2load uses scheme, host and
133 port in the first URI in command-line or input file.
138 h2load supports HTTP/3 if it is built with HTTP/3 enabled. HTTP/3
139 support is experimental.
141 In order to send HTTP/3 request, specify ``h3`` to
142 :option:`--npn-list`.