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.  To adjust receiver flow control window size,
  54 there is following options:
  55
  56 ``-w``
  57    Sets  the stream  level  initial  window size  to
  58    (2**<N>)-1.  For SPDY, 2**<N> is used instead.
  59
  60 ``-W``
  61    Sets the connection level  initial window size to
  62    (2**<N>)-1.  For  SPDY, if  <N> is  strictly less
  63    than  16,  this  option  is  ignored.   Otherwise
  64    2**<N> is used for SPDY.
  65
  66 Multi-Threading
  67 ---------------
  68
  69 Sometimes benchmarking client itself becomes a bottleneck.  To remedy
  70 this situation, use ``-t`` option to specify the number of native
  71 thread to use.
  72
  73 ``-t``
  74     The number of native threads. Default: 1
  75
  76 Selecting protocol for clear text
  77 ---------------------------------
  78
  79 By default, if \http:// URI is given, HTTP/2 protocol is used.  To
  80 change the protocol to use for clear text, use ``-p`` option.
  81
  82 Multiple URIs
  83 -------------
  84
  85 If multiple URIs are specified, they are used in round robin manner.
  86
  87 .. note::
  88
  89     Please note that h2load uses sheme, host and port in the first URI
  90     and ignores those parts in the rest of the URIs.