doc/sources/h2load-howto.rst

   1 .. program:: h2load
   2
   3 h2load - HTTP/2 benchmarking tool - HOW-TO
   4 ==========================================
   5
   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.
   8
   9 Compiling from source
  10 ---------------------
  11
  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:
  16 Building from Git
  17 <https://github.com/nghttp2/nghttp2#building-from-git>`_.
  18
  19 Basic Usage
  20 -----------
  21
  22 In 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
  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.
  39
  40 Here is a command-line to perform benchmark to URI \https://localhost
  41 using total 100000 requests, 100 concurrent clients and 10 max
  42 concurrent streams:
  43
  44 .. code-block:: text
  45
  46     $ h2load -n100000 -c100 -m10 https://localhost
  47
  48 The 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
  62 See the h2load manual page :ref:`h2load-1-output` section for the
  63 explanation of the above numbers.
  64
  65 Timing-based load-testing
  66 -------------------------
  67
  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.
  76
  77 The following command performs load-testing for 10 seconds after 5
  78 seconds warming up period:
  79
  80 .. code-block:: text
  81
  82     $ h2load -c100 -m100 --duration=10 --warm-up-time=5 https://localhost
  83
  84 Flow Control
  85 ------------
  86
  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:
  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
 100 Multi-Threading
 101 ---------------
 102
 103 Sometimes benchmarking client itself becomes a bottleneck.  To remedy
 104 this situation, use :option:`-t` option to specify the number of native
 105 thread to use.
 106
 107 :option:`-t`
 108     The number of native threads. Default: 1
 109
 110 Selecting protocol for clear text
 111 ---------------------------------
 112
 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.
 115
 116 Multiple URIs
 117 -------------
 118
 119 If 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
 126 UNIX domain socket
 127 ------------------
 128
 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.