httperf.man

一个WEB服务器的性能测试工具

prefix is followed by the call's serial number and a colon (":")
character that marks the beginning of the actual reply line.  To print
only request headers, pass argument
.B header
to this option.  To print only the request body, pass argument
.B body
to this option.
.TP
.BI --rate= X
Specifies the fixed rate at which connections or sessions are created.
Connections are created by default, sessions if option
.B --wsess
or
.B --wsesslog
has been specified.  In both cases a rate of 0 results in connections
or sessions being generated sequentially (a new session/connection is
initiated as soon as the previous one completes).  The default value
for this option is 0.
.TP
.BI --recv-buffer= N
Specifies the maximum size of the socket receive buffers used to
receive HTTP replies.  By default, the limit is 16KB.  A smaller value
may help memory-constrained clients whereas a larger value may be
necessary when communicating with a server over a high-bandwidth,
high-latency connection.
.TP
.BI --retry-on-failure
This option is meaningful for session workloads only (see the
.B --wsess
and
.B --wsesslog
options).  If specified, a call that results in a failure response (as
defined by the
.B --failure-status
option) is retried immediately instead of causing the session to fail.
.TP
.BI --send-buffer= N
Specifies the maximum size of the socket send buffers used to send
HTTP requests.  By default, the limit is 4KB.  A smaller value may
help memory-constrained clients whereas a larger value may be
necessary when generating large requests to a server connected via a
high-bandwidth, high-latency connection.
.TP
.BI --server= S
Specifies the IP hostname of the server.  By default, the hostname
``localhost'' is used.  This option should always be specified as it
is generally not a good idea to run the client and the server on the
same machine.
.TP
.BI --server-name= S
Specifies the (default) server name that appears in the "Host:" header
of every request sent by
.BR httperf .
Without this option, the host name (or IP address) specified by option
.B --server
is used instead.
.TP
.B --session-cookie
When this option is turned on, cookie managment is enabled on a
per-session basis.  What this means is that if a reply to a request
that was generated by session
.IR X 
contains a cookie, then all future requests sent by session
.I X
will include this cookie as well.  At present, the cookie manager in
.B httperf
supports only one cookie per session.  If a second cookie is received,
the new cookie overwrites the existing one and a warning message is
printed if ``--debug 1'' is on.
.TP
.B --ssl
Specifies that all communication between
.B httperf
and the server should utilize the Secure Sockets Layer (SSL) protocol.
This option is available only if
.B httperf
was compiled with SSL support enabled.
.TP
.BI --ssl-ciphers= L
This option is only meaningful if SSL is in use (see
.B --ssl
option).  This option specifies the list
.I L
of cipher suites that
.B httperf
may use in negotiating a secure connection with the server.  If the
list contains more than one cipher suite, the ciphers must be
separated by a colon.  If the server does not accept any of the listed
cipher suites, the connection establishment will fail and
.B httperf
will exit immediately.  If this option is not specified when the
.B --ssl
option is present then
.B httperf
will use all of the SSLv3 cipher suites provided by the underlying SSL
library.
.TP
.B --ssl-no-reuse
This option is only meaningful if SSL and sessions are in use (see
.BR --ssl ,
.BR --wsess ,
.BR --wsesslog ).
When an SSL connection is established the client receives a session
identifier (session id) from the server.  On subsequent SSL
connections, the client normally reuses this session id in order to
avoid the expense of repeating the (slow) SSL handshake to establish a
new SSL session and obtain another session id (even if the client
attempts to re-use a session id, the server may force the client to
renegotiate a session).  By default
.B httperf
reuses the session id across all connections in a session.  If the
.B --ssl-no-reuse
option is in effect, then
.B httperf
will not reuse the session id, and the entire SSL handshake will be
performed for each new connection in a session.
.TP
.BI --think-timeout= X
Specifies the maximum time that the server may need to initiate
sending the reply for a given request.  Note that this timeout value
is added to the normal timeout value (see option
.BR --timeout ).
When accessing static web content, it is usually not necessary to
specify this option.  However, when performing tests with long-running
CGI scripts, it may be necessary to use this option to allow for
larger response-times.  The default value for this option is zero
seconds, meaning that the server has to be able to respond within the
normal timeout value.
.TP
.BI --timeout= X
Specifies the amount of time
.I X
that
.B httperf
is willing to wait for a server reaction.  The timeout is specified in
seconds and can be a fractional number (e.g.,
.BR "--timeout 3.5" ).
This timeout value is used when establishing a TCP connection, when
sending a request, when waiting for a reply, and when receiving a
reply.  If during any of those activities a request fails to make
forward progress within the alloted time,
.B httperf
considers the request to have died, closes the associated connection
or session and increases the
.B client-timo
error count.  The actual timeout value used when waiting for a reply
is the sum of this timeout and the think-timeout (see option
.BR --think-timeout ).
By default, the timeout value is infinity.
.TP
.BI --uri= S
Specifies that URI
.I S
should be accessed on the server.  For some of the workload generators
(e.g.,
.BR --wset ),
this option specifies the prefix for the URIs being accessed.
.TP
.B -v
.TP
.B --verbose
Puts
.B httperf
into verbose mode.  In this mode, additional output such as the
individual reply rate samples and connection lifetime histogram are
printed.
.TP
.B -V
.TP
.B --version
Prints the version of
.BR httperf .
.TP
.BI --wlog= B , F
This option can be used to generate a specific sequence of URI
accesses.  This is useful to replay the accesses recorded in a server
log file, for example.  Parameter
.I F
is the name of a file containing the ASCII NUL separated list of URIs
that should be accessed.  If parameter
.I B
is set to
.RB `` y '',
.B httperf
will wrap around to the beginning of the file when reaching the end of
the list (so the list of URIs is accessed repeatedly).  With
.I B
set to
.RB `` n '',
the test will stop no later than when reaching the end of the URI
list.
.TP
.BI --wsess= N1 , N2 , X
Requests the generation and measurement of sessions instead of
individual requests.  A session consists of a sequence of bursts which
are spaced out by the user think-time.  Each burst consists of a fixed
number
.I L
of calls to the server
.RI ( L
is specified by option
.BR --burst-length ).
The calls in a burst are issued as follows: at first, a single call is
issued.  Once the reply to this first call has been fully received,
all remaining calls in the burst are issued concurrently.  The
concurrent calls are issued either as pipelined calls on an existing
persistent connection or as individual calls on separate connections.
Whether a persistent connection is used depends on whether the server
responds to the first call with a reply that includes a ``Connection:
close'' header line.  If such a line is present, separate connections
are used.

The option specifies the following parameters:
.I N1
is the total number of sessions to generate,
.I N2
is the number of calls per session, and
.I X
is the user think-time (in seconds) that separates consecutive call
bursts.  For example, the options
.RB `` "--wsess=100,50,10 --burst-len 5" ''
would result in 100 sessions with a total of 50 calls each.  Since
each burst has a length of 5 calls, a total of 10 call bursts would be
generated per session.  The user think-time between call bursts would
be 10 seconds.  Note that user think-time
.I X
denotes the time between receiving the last reply of the previous
call burst and the sending of the first request of the next burst.

A test involving sessions finishes as soon as the requested number
.I N1
of sessions have either failed or completed.  A session is considered
to have failed if any operation in a session takes longer than
the timeouts specified by options
.B --timeout
and
.BR --think-timeout .
In addition, a session also fails if the server returns a reply with a
status code matching the one specified by option
.BR --failure-status .
.TP
.BI --wsesslog= N , X , F
This specifies a session workload generator similar to
.B --wsess
(please read that description first).  With
.B --wsesslog
though, many aspects of user sessions, including the number and
sequence of URI's, request method, think-time and burst-length parameters, 
can be specified in an input file
.I F.
Two other parameters are retained from
.B --wsess,
namely
.I N,
the number of sessions to initiate, and
.I X,
the burst-to-burst user think time (note that this becomes a default
time since the input file
.I F
can also specify user think time on a per-burst basis.
A small example input file can most-easily show the settable parameters:
.br

.br
# Comment lines start with a ``#'' as the first
.br
# character.  Lines with only whitespace delimit
.br
# sessions (multiple blank lines do not generate
.br
# ``null'' sessions).  All other lines specify a
.br
# uri-sequence (1 uri per line).  If the first
.br
# character of the line is whitespace (e.g. space
.br
# or tab), the uri is considered to be part of a
.br
# burst that is sent out after the previous
.br
# non-burst uri.
.br

.br
# session 1 definition (this is a comment)
.br
/foo.html think=2.0
.br
	/pict1.gif
.br
	/pict2.gif
.br
/foo2.html method=POST contents='Post data'
.br
	/pict3.gif
.br
	/pict4.gif
.br
	
.br
# session 2 definition
.br
/foo3.html method=POST contents="Multiline\\ndata"
.br
/foo4.html method=HEAD
.br

.br
The above description specifies 2 sessions.  The first session will
start with a request for /foo.html.  When the /foo.html response comes
back, a burst of 2 requests will follow (/pict1.gif and /pict2.gif).
When the last of those responses is received, a two second user think
time is inserted before the next request of /foo2.html is issued.
This request is sent as a POST.  The posted data can be contained
between single- or double-quotes.  Newlines can appear within posted
data as ``\\n'' or as a ``\\<CR>''.  The /foo2.html response is
followed by a burst request of /pict3.gif and /pict4.gif, which
concludes this session.  The second session is started some time after
the first, as specified by the
.B --rate
or
.B --period
options.
.br	

.br
The second session consists of 2 requests separated by the default user think
time as specified by the
.I X
parameter of the
.B --wsesslog
option.  If the
.I N
parameter of
.B --wsesslog
is greater than the number of sessions defined in input file
.IR F ,
then the defined sessions are used repeatedly until
.I N
sessions have been created (i.e., the defined sessions are used in a
round-robin fashion).
.br
	
.br
One should avoid using
.B --wsesslog
in conjunction with other
.B httperf
options that also control session behavior and workload URI's, namely
.B --burst-length,
.B --wsess,
.B --wlog,
and
.B --wset.
.TP
.BI --wset= N , X
This option can be used to walk through a list of URIs at a given
rate.  Parameter
.I N
specifies the number of distinct URIs that should be generated and
.I X
specifies the rate at which new URIs are accessed.  A rate of
.B 0.25
would mean that the same URI would be accessed four times in a row
before moving on to the next URI.  This type of access pattern is
useful in generating a workload that induces a relatively predictable
amount of traffic in the disk I/O subsystem of the server (assuming
.I N
and the accessed files are big enough to exceed the server's buffer
cache).  The URIs generated are of the form
.IR	prefix / path .html,
where
.I prefix
is the URI prefix specified by option
.B --wset
and
.I path
is generated as follows: for the
.IR i -th
file in the working set, write down
.I i
in decimal, prefixing the number with as many zeroes as necessary
to get a string that has as many digits as
.IR N -1.
Then insert a slash character between each digit.  For example,
the 103rd file in a working set consisting of 1024 files would
result in a path of
.RB `` 0/1/0/3 ''.