doc/sources/h2load-howto.rst

   1 h2load - HTTP/2 benchmarking tool - HOW-TO
   2 ==========================================
   3
   4 h2load is benchmarking tool for HTTP/2.  If built with
   5 spdylay (http://tatsuhiro-t.github.io/spdylay/) library, it also
   6 supports SPDY protocol.  It supports SSL/TLS and clear text for both
   7 HTTP/2 and SPDY.
   8
   9 Basic Usage
  10 -----------
  11
  12 In order to set benchmark settings, specify following 3 options.
  13
  14 ``-n``
  15     The number of total requests.  Default: 1
  16
  17 ``-c``
  18     The number of concurrent clients.  Default: 1
  19
  20 ``-m``
  21    The max concurrent streams to issue per client.
  22    If ``auto`` is given, the number of given URIs is used.
  23    Default: ``auto``
  24
  25 Here is a command-line to perform benchmark to URI \https://localhost
  26 using total 100000 requests, 100 concurrent clients and 10 max
  27 concurrent streams::
  28
  29     $ h2load -n100000 -c100 -m10 https://localhost
  30
  31 The benchmarking result looks like this::
  32
  33     finished in 0 sec, 385 millisec and 851 microsec, 2591 req/s, 1689 kbytes/s
  34     requests: 1000 total, 1000 started, 1000 done, 1000 succeeded, 0 failed, 0 errored
  35     status codes: 1000 2xx, 0 3xx, 0 4xx, 0 5xx
  36     traffic: 667500 bytes total, 28700 bytes headers, 612000 bytes data
  37
  38 The number of ``failed`` is the number of requests returned with non
  39 2xx status.  The number of ``error`` is the number of ``failed`` plus
  40 the number of requests which failed with connection error.
  41
  42 The number of ``total`` in ``traffic`` is the received application
  43 data.  If SSL/TLS is used, this number is calculated after decryption.
  44 The number of ``headers`` is the sum of payload size of response
  45 HEADERS (or SYN_REPLY for SPDY).  This number comes before
  46 decompressing header block.  The number of ``data`` is the sum of
  47 response body.
  48
  49 Flow Control
  50 ------------
  51
  52 HTTP/2 and SPDY/3 or later employ flow control and it may affect
  53 benchmarking results.  By default, h2load uses large enough flow
  54 control window, which effectively disables flow control.  To adjust
  55 receiver flow control window size, there are following options:
  56
  57 ``-w``
  58    Sets  the stream  level  initial  window size  to
  59    (2**<N>)-1.  For SPDY, 2**<N> is used instead.
  60
  61 ``-W``
  62    Sets the connection level  initial window size to
  63    (2**<N>)-1.  For  SPDY, if  <N> is  strictly less
  64    than  16,  this  option  is  ignored.   Otherwise
  65    2**<N> is used for SPDY.
  66
  67 Multi-Threading
  68 ---------------
  69
  70 Sometimes benchmarking client itself becomes a bottleneck.  To remedy
  71 this situation, use ``-t`` option to specify the number of native
  72 thread to use.
  73
  74 ``-t``
  75     The number of native threads. Default: 1
  76
  77 Selecting protocol for clear text
  78 ---------------------------------
  79
  80 By default, if \http:// URI is given, HTTP/2 protocol is used.  To
  81 change the protocol to use for clear text, use ``-p`` option.
  82
  83 Multiple URIs
  84 -------------
  85
  86 If multiple URIs are specified, they are used in round robin manner.
  87
  88 .. note::
  89
  90     Please note that h2load uses scheme, host and port in the first URI
  91     and ignores those parts in the rest of the URIs.