diff options
Diffstat (limited to 'doc/sources/h2load-howto.rst')
| -rw-r--r-- | doc/sources/h2load-howto.rst | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/doc/sources/h2load-howto.rst b/doc/sources/h2load-howto.rst new file mode 100644 index 0000000..2ee2754 --- /dev/null +++ b/doc/sources/h2load-howto.rst @@ -0,0 +1,142 @@ +.. program:: h2load + +h2load - HTTP/2 benchmarking tool - HOW-TO +========================================== + +:doc:`h2load.1` is benchmarking tool for HTTP/2 and HTTP/1.1. It +supports SSL/TLS and clear text for all supported protocols. + +Compiling from source +--------------------- + +h2load is compiled alongside nghttp2 and requires that the +``--enable-app`` flag is passed to ``./configure`` and `required +dependencies <https://github.com/nghttp2/nghttp2#requirements>`_ are +available during compilation. For details on compiling, see `nghttp2: +Building from Git +<https://github.com/nghttp2/nghttp2#building-from-git>`_. + +Basic Usage +----------- + +In order to set benchmark settings, specify following 3 options. + +:option:`-n` + The number of total requests. Default: 1 + +:option:`-c` + The number of concurrent clients. Default: 1 + +:option:`-m` + The max concurrent streams to issue per client. Default: 1 + +For SSL/TLS connection, the protocol will be negotiated via ALPN/NPN. +You can set specific protocols in :option:`--npn-list` option. For +cleartext connection, the default protocol is HTTP/2. To change the +protocol in cleartext connection, use :option:`--no-tls-proto` option. +For convenience, :option:`--h1` option forces HTTP/1.1 for both +cleartext and SSL/TLS connections. + +Here is a command-line to perform benchmark to URI \https://localhost +using total 100000 requests, 100 concurrent clients and 10 max +concurrent streams: + +.. code-block:: text + + $ h2load -n100000 -c100 -m10 https://localhost + +The benchmarking result looks like this: + +.. code-block:: text + + finished in 7.08s, 141164.80 req/s, 555.33MB/s + requests: 1000000 total, 1000000 started, 1000000 done, 1000000 succeeded, 0 failed, 0 errored, 0 timeout + status codes: 1000000 2xx, 0 3xx, 0 4xx, 0 5xx + traffic: 4125025824 bytes total, 11023424 bytes headers (space savings 93.07%), 4096000000 bytes data + min max mean sd +/- sd + time for request: 15.31ms 146.85ms 69.78ms 9.26ms 92.43% + time for connect: 1.08ms 25.04ms 10.71ms 9.80ms 64.00% + time to 1st byte: 25.36ms 184.96ms 79.11ms 53.97ms 78.00% + req/s (client) : 1412.04 1447.84 1426.52 10.57 63.00% + +See the h2load manual page :ref:`h2load-1-output` section for the +explanation of the above numbers. + +Timing-based load-testing +------------------------- + +As of v1.26.0, h2load supports timing-based load-testing. This method +performs load-testing in terms of a given duration instead of a +pre-defined number of requests. The new option :option:`--duration` +specifies how long the load-testing takes. For example, +``--duration=10`` makes h2load perform load-testing against a server +for 10 seconds. You can also specify a “warming-up” period with +:option:`--warm-up-time`. If :option:`--duration` is used, +:option:`-n` option is ignored. + +The following command performs load-testing for 10 seconds after 5 +seconds warming up period: + +.. code-block:: text + + $ h2load -c100 -m100 --duration=10 --warm-up-time=5 https://localhost + +Flow Control +------------ + +HTTP/2 has flow control and it may affect benchmarking results. By +default, h2load uses large enough flow control window, which +effectively disables flow control. To adjust receiver flow control +window size, there are following options: + +:option:`-w` + Sets the stream level initial window size to + (2**<N>)-1. + +:option:`-W` + Sets the connection level initial window size to + (2**<N>)-1. + +Multi-Threading +--------------- + +Sometimes benchmarking client itself becomes a bottleneck. To remedy +this situation, use :option:`-t` option to specify the number of native +thread to use. + +:option:`-t` + The number of native threads. Default: 1 + +Selecting protocol for clear text +--------------------------------- + +By default, if \http:// URI is given, HTTP/2 protocol is used. To +change the protocol to use for clear text, use :option:`-p` option. + +Multiple URIs +------------- + +If multiple URIs are specified, they are used in round robin manner. + +.. note:: + + Please note that h2load uses scheme, host and port in the first URI + and ignores those parts in the rest of the URIs. + +UNIX domain socket +------------------ + +To request against UNIX domain socket, use :option:`--base-uri`, and +specify ``unix:`` followed by the path to UNIX domain socket. For +example, if UNIX domain socket is ``/tmp/nghttpx.sock``, use +``--base-uri=unix:/tmp/nghttpx.sock``. h2load uses scheme, host and +port in the first URI in command-line or input file. + +HTTP/3 +------ + +h2load supports HTTP/3 if it is built with HTTP/3 enabled. HTTP/3 +support is experimental. + +In order to send HTTP/3 request, specify ``h3`` to +:option:`--npn-list`. |