1.. program:: h2load 2 3h2load - HTTP/2 benchmarking tool - HOW-TO 4========================================== 5 6:doc:`h2load.1` is benchmarking tool for HTTP/2 and HTTP/1.1. It 7supports SSL/TLS and clear text for all supported protocols. 8 9Compiling from source 10--------------------- 11 12h2load is compiled alongside nghttp2 and requires that the 13``--enable-app`` flag is passed to ``./configure`` and `required 14dependencies <https://github.com/nghttp2/nghttp2#requirements>`_ are 15available during compilation. For details on compiling, see `nghttp2: 16Building from Git 17<https://github.com/nghttp2/nghttp2#building-from-git>`_. 18 19Basic Usage 20----------- 21 22In order to set benchmark settings, specify following 3 options. 23 24:option:`-n` 25 The number of total requests. Default: 1 26 27:option:`-c` 28 The number of concurrent clients. Default: 1 29 30:option:`-m` 31 The max concurrent streams to issue per client. Default: 1 32 33For SSL/TLS connection, the protocol will be negotiated via ALPN/NPN. 34You can set specific protocols in :option:`--npn-list` option. For 35cleartext connection, the default protocol is HTTP/2. To change the 36protocol in cleartext connection, use :option:`--no-tls-proto` option. 37For convenience, :option:`--h1` option forces HTTP/1.1 for both 38cleartext and SSL/TLS connections. 39 40Here is a command-line to perform benchmark to URI \https://localhost 41using total 100000 requests, 100 concurrent clients and 10 max 42concurrent streams: 43 44.. code-block:: text 45 46 $ h2load -n100000 -c100 -m10 https://localhost 47 48The benchmarking result looks like this: 49 50.. code-block:: text 51 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% 61 62See the h2load manual page :ref:`h2load-1-output` section for the 63explanation of the above numbers. 64 65Timing-based load-testing 66------------------------- 67 68As of v1.26.0, h2load supports timing-based load-testing. This method 69performs load-testing in terms of a given duration instead of a 70pre-defined number of requests. The new option :option:`--duration` 71specifies how long the load-testing takes. For example, 72``--duration=10`` makes h2load perform load-testing against a server 73for 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. 76 77The following command performs load-testing for 10 seconds after 5 78seconds warming up period: 79 80.. code-block:: text 81 82 $ h2load -c100 -m100 --duration=10 --warm-up-time=5 https://localhost 83 84Flow Control 85------------ 86 87HTTP/2 has flow control and it may affect benchmarking results. By 88default, h2load uses large enough flow control window, which 89effectively disables flow control. To adjust receiver flow control 90window size, there are following options: 91 92:option:`-w` 93 Sets the stream level initial window size to 94 (2**<N>)-1. 95 96:option:`-W` 97 Sets the connection level initial window size to 98 (2**<N>)-1. 99 100Multi-Threading 101--------------- 102 103Sometimes benchmarking client itself becomes a bottleneck. To remedy 104this situation, use :option:`-t` option to specify the number of native 105thread to use. 106 107:option:`-t` 108 The number of native threads. Default: 1 109 110Selecting protocol for clear text 111--------------------------------- 112 113By default, if \http:// URI is given, HTTP/2 protocol is used. To 114change the protocol to use for clear text, use :option:`-p` option. 115 116Multiple URIs 117------------- 118 119If multiple URIs are specified, they are used in round robin manner. 120 121.. note:: 122 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. 125 126UNIX domain socket 127------------------ 128 129To request against UNIX domain socket, use :option:`--base-uri`, and 130specify ``unix:`` followed by the path to UNIX domain socket. For 131example, if UNIX domain socket is ``/tmp/nghttpx.sock``, use 132``--base-uri=unix:/tmp/nghttpx.sock``. h2load uses scheme, host and 133port in the first URI in command-line or input file. 134 135HTTP/3 136------ 137 138h2load supports HTTP/3 if it is built with HTTP/3 enabled. HTTP/3 139support is experimental. 140 141In order to send HTTP/3 request, specify ``h3`` to 142:option:`--npn-list`. 143