Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
H2LOAD(1)			    nghttp2			     H2LOAD(1)

NAME
       h2load -	HTTP/2 benchmarking tool

SYNOPSIS
       h2load [OPTIONS]... [URI]...

DESCRIPTION
       benchmarking tool for HTTP/2 server

       <URI>  Specify  URI  to access.	 Multiple URIs can be specified.  URIs
	      are used	in this	order for each	client.	 All  URIs  are	 used,
	      then   first  URI	 is  used  and then  2nd URI, and so  on.  The
	      scheme, host  and	port  in the   subsequent  URIs,  if  present,
	      are  ignored.  Those in  the first URI are used solely.  Defini-
	      tion of a	base URI overrides all scheme, host or port values.

OPTIONS
       -n, --requests=<N>
	      Number of	 requests across all  clients.	If it	is  used  with
	      --timing-script-file  option,   this option specifies the	number
	      of requests  each	client performs	rather than the	number of  re-
	      quests   across  all  clients.   This  option is ignored if tim-
	      ing-based	 benchmarking is enabled (see --duration option).

	      Default: 1

       -c, --clients=<N>
	      Number  of concurrent  clients.	With  -r option,  this	speci-
	      fies the maximum number of connections to	be made.

	      Default: 1

       -t, --threads=<N>
	      Number of	native threads.

	      Default: 1

       -i, --input-file=<PATH>
	      Path  of	a file with multiple URIs are separated	by EOLs.  This
	      option will disable URIs getting from command-line.  If  '-'  is
	      given  as	 <PATH>,  URIs will be read from stdin.	 URIs are used
	      in this order for	each  client.  All URIs	are used, then	 first
	      URI  is  used  and then  2nd URI,	and so	on.  The  scheme, host
	      and port	in the	subsequent URIs,  if  present,	 are  ignored.
	      Those  in	  the first URI	are used solely.  Definition of	a base
	      URI overrides all	scheme,	host or	port values.

       -m, --max-concurrent-streams=<N>
	      Max   concurrent	 streams   to  issue   per   session.	  When
	      http/1.1	 is  used,  this  specifies the	 number	of  HTTP pipe-
	      lining requests in-flight.

	      Default: 1

       -w, --window-bits=<N>
	      Sets the stream level initial window size	to (2**<N>)-1.

	      Default: 30

       -W, --connection-window-bits=<N>
	      Sets   the   connection	level	 initial   window   size    to
	      (2**<N>)-1.

	      Default: 30

       -H, --header=<HEADER>
	      Add/Override a header to the requests.

       --ciphers=<SUITE>
	      Set  allowed   cipher  list.   The  format of the	 string	is de-
	      scribed in OpenSSL ciphers(1).

	      Default:
	      ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256

       -p, --no-tls-proto=<PROTOID>
	      Specify ALPN identifier of the  protocol to be used when access-
	      ing  http	 URI  without  SSL/TLS.	  Available protocols: h2c and
	      http/1.1

	      Default: h2c

       -d, --data=<PATH>
	      Post FILE	to  server.  The request method	 is changed  to	 POST.
	      For   http/1.1 connection,  if  -d  is used,  the	maximum	number
	      of in-flight pipelined requests is set to	1.

       -r, --rate=<N>
	      Specifies	 the  fixed  rate  at  which   connections   are  cre-
	      ated.   The   rate  must	 be  a	 positive  integer, represent-
	      ing the  number of  connections to be   made  per	 rate  period.
	      The  maximum   number  of	connections  to	be made	 is  given  in
	      -c   option.   This  rate	 will  be distributed  among   threads
	      as   evenly  as  possible.  For example,	with   -t2  and	  -r4,
	      each  thread   gets  2 connections per period.  When the rate is
	      0, the program will run  as it  normally does, creating  connec-
	      tions at whatever	variable rate it  wants.   The	default	 value
	      for this option is 0.  -r	and -D are mutually exclusive.

       --rate-period=<DURATION>
	      Specifies	 the  time   period between creating connections.  The
	      period  must be a	positive  number, representing the  length  of
	      the  period  in time.  This option is ignored if the rate	option
	      is not used.  The	default	value for this option is 1s.

       -D, --duration=<N>
	      Specifies	the main duration for the measurements in case of tim-
	      ing-based	 benchmarking.	-D  and	-r  are	mutually exclusive.

       --warm-up-time=<DURATION>
	      Specifies	 the   time   period  before  starting the actual mea-
	      surements, in  case  of  timing-based  benchmarking.   Needs  to
	      provided along with -D option.

       -T, --connection-active-timeout=<DURATION>
	      Specifies	  the maximum  time that  h2load is  willing to	keep a
	      connection open,	regardless of the  activity  on	 said  connec-
	      tion.   <DURATION>  must	be  a positive integer,	specifying the
	      amount of	time  to wait.	When no	timeout	value is  set  (either
	      active  or inactive),  h2load will keep  a  connection  open in-
	      definitely,  waiting  for	 a response.

       -N, --connection-inactivity-timeout=<DURATION>
	      Specifies	the amount  of time that h2load	 is willing to wait to
	      see  activity   on  a  given  connection.	 <DURATION> must  be a
	      positive integer,	 specifying the	  amount  of  time   to	 wait.
	      When  no	 timeout  value	  is set  (either active or inactive),
	      h2load  will keep	a connection open indefinitely,	waiting	for  a
	      response.

       --timing-script-file=<PATH>
	      Path  of	a file containing one or more lines separated by EOLs.
	      Each script line is composed of two tab-separated	 fields.   The
	      first  field represents the time offset from the start of	execu-
	      tion, expressed as a positive value of  milliseconds   with  mi-
	      crosecond	  resolution.	The   second field represents the URI.
	      This option will disable URIs getting  from   command-line.   If
	      '-'  is  given as	<PATH>,	script lines will be read  from	stdin.
	      Script lines are used in order  for  each	 client.    If	-n  is
	      given, it	must be	less  than or  equal to	the  number of	script
	      lines, larger values are clamped to the number of	script	lines.
	      If  -n is	not given,  the	number of requests will	default	to the
	      number of	 script	lines.	 The scheme,  host and port defined in
	      the  first  URI  are   used solely.  Values contained  in	 other
	      URIs,  if	 present,  are	ignored.  Definition of	 a   base  URI
	      overrides	all  scheme, host or port values.

       -B, --base-uri=(<URI>|unix:<PATH>)
	      Specify  URI  from  which	the scheme, host and port will be used
	      for  all requests.   The	base  URI overrides  all  values   de-
	      fined  either  at	 the command  line or  inside input files.  If
	      argument	starts with "unix:", then the rest  of	the   argument
	      will   be	treated	 as UNIX  domain socket	path.	The connection
	      is made  through that path  instead  of  TCP.    In  this	 case,
	      scheme   is  inferred from the first  URI	appeared  in the  com-
	      mand line	 or inside input files as usual.

       --npn-list=<LIST>
	      Comma delimited list of  ALPN protocol identifier	sorted in  the
	      order  of	preference.  That  means most desirable	protocol comes
	      first.  This  is used  in	both  ALPN  and	 NPN.	The  parameter
	      must be  delimited by a single comma only	 and any  white	spaces
	      are  treated as  a part  of protocol string.

	      Default: h2,h2-16,h2-14,http/1.1

       --h1   Short	     hand	     for	   --npn-list=http/1.1
	      --no-tls-proto=http/1.1,	     which	effectively	 force
	      http/1.1 for both	http and https URI.

       --header-table-size=<SIZE>
	      Specify decoder header table size.

	      Default: 4K

       --encoder-header-table-size=<SIZE>
	      Specify encoder header table size.  The decoder (server)	speci-
	      fies   the  maximum   dynamic table  size	it  accepts.  Then the
	      negotiated dynamic table size is	the  minimum  of  this	option
	      value and	the value which	server specified.

	      Default: 4K

       --log-file=<PATH>
	      Write  per-request  information  to a file as tab-separated col-
	      umns: start  time	as  microseconds  since	  epoch;  HTTP	status
	      code;  microseconds until	end of	response.  More	columns	may be
	      added later.  Rows are ordered by	end-of-	 response   time  when
	      using   one worker  thread, but  may appear slightly  out	of or-
	      der with	multiple threads due to	buffering.  Status code	is  -1
	      for failed streams.

       --connect-to=<HOST>[:<PORT>]
	      Host  and	 port  to  connect   instead of	using the authority in
	      <URI>.

       -v, --verbose
	      Output debug information.

       --version
	      Display version information and exit.

       -h, --help
	      Display this help	and exit.

       The <SIZE> argument is an integer and an	optional unit (e.g., 10K is 10
       * 1024).	 Units are K, M	and G (powers of 1024).

       The <DURATION> argument is an integer and an optional unit (e.g., 1s is
       1 second	and 500ms is 500 milliseconds).	 Units	are  h,	 m,  s	or  ms
       (hours, minutes,	seconds	and milliseconds, respectively).  If a unit is
       omitted,	a second is used as unit.

OUTPUT
       requests

	      total  The number	of requests h2load was instructed to make.

	      started
		     The number	of requests h2load has started.

	      done   The number	of requests completed.

	      succeeded
		     The number	of requests completed successfully.  Only HTTP
		     status code 2xx or3xx are considered as success.

	      failed The number	of requests failed, including HTTP level fail-
		     ures (non-successful HTTP status code).

	      errored
		     The number	of requests  failed,  except  for  HTTP	 level
		     failures.	 This  is the subset of	the number reported in
		     failed and	most likely  the  network  level  failures  or
		     stream was	reset by RST_STREAM.

	      timeout
		     The  number of requests whose connection timed out	before
		     they were completed.   This  is  the   subset    of   the
		     number  reported  in errored.

       status codes
	      The number of status code	h2load received.

       traffic

	      total  The  number  of  bytes  received  from the	server "on the
		     wire".  If	requests were made via TLS, this value is  the
		     number of decrypted bytes.

	      headers
		     The  number  of response  header  bytes  from the	server
		     without decompression.  The  space	 savings  shows	 effi-
		     ciency  of	header compression.  Let decompressed(headers)
		     to	the number of bytes used for header fields  after  de-
		     compression.   The	 space	savings	is calculated  by (1 -
		     headers  /	decompressed(headers)) * 100.	For  HTTP/1.1,
		     this  is  usually	 0.00%,	 since it does not have	header
		     compression.  For HTTP/2, it shows	some  insightful  num-
		     bers.

	      data   The  number  of  response	body  bytes  received from the
		     server.

       time for	request

	      min    The minimum time taken for	request	and response.

	      max    The maximum time taken for	request	and response.

	      mean   The mean time taken for request and response.

	      sd     The standard deviation of the time	taken for request  and
		     response.

	      +/- sd The  fraction  of	the number of requests within standard
		     deviation range (mean +/- sd)  against  total  number  of
		     successful	requests.

       time for	connect

	      min    The  minimum  time	taken to connect to a server including
		     TLS handshake.

	      max    The maximum time taken to connect to a  server  including
		     TLS handshake.

	      mean   The  mean time taken to connect to	a server including TLS
		     handshake.

	      sd     The standard deviation of the time	taken to connect to  a
		     server.

	      +/- sd The   fraction  of	 the   number  of  connections	within
		     standard deviation	range (mean   +/-  sd)	against	 total
		     number of successful connections.

       time for	1st byte (of (decrypted	in case	of TLS)	application data)

	      min    The minimum time taken to get 1st byte from a server.

	      max    The maximum time taken to get 1st byte from a server.

	      mean   The mean time taken to get	1st byte from a	server.

	      sd     The  standard deviation of	the time taken to get 1st byte
		     from a server.

	      +/- sd The fraction of the number	of connections within standard
		     deviation	range  (mean  +/-  sd) against total number of
		     successful	connections.

       req/s

	      min    The minimum request per second among all clients.

	      max    The maximum request per second among all clients.

	      mean   The mean request per second among all clients.

	      sd     The standard deviation of request per  second  among  all
		     clients.  server.

	      +/- sd The fraction of the number	of connections within standard
		     deviation range (mean +/- sd)  against  total  number  of
		     successful	connections.

FLOW CONTROL
       h2load  sets large flow control window by default, and effectively dis-
       ables flow control to avoid under utilization  of  server  performance.
       To  set	smaller	flow control window, use -w and	-W options.  For exam-
       ple, use	-w16 -W16 to set default window	size described in HTTP/2  pro-
       tocol specification.

SEE ALSO
       nghttp(1), nghttpd(1), nghttpx(1)

AUTHOR
       Tatsuhiro Tsujikawa

COPYRIGHT
       2012, 2015, 2016, Tatsuhiro Tsujikawa

1.41.0				 Jun 02, 2020			     H2LOAD(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT | FLOW CONTROL | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=h2load&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help