Documentation has been synchronized with Poly 2.1.0.

usage: polyclt [--option] ...
options:

help	list of options
version	package version info
host_type	package build environment information
verb_lvl <int>	console verbosity level
dump <list>	dump request/replies/errors headers/bodies to console
prn_reqs <bool>	dump request headers to console
prn_reps <bool>	dump reply headers to console
prn_errs <bool>	dump detailed message info for every xaction error
notify <addr>	send notifications to a [remote] monitoring program
label <str>	run label
fd_limit <int>	decrease default fd limit
config <file>	configuration file name
cfg_dirs <list>	directories to search for cfg files
console <file>	redirect console output
log <file>	detailed binary log file
log_size <size>	binary log size limit
stats_cycle <time>	statistics cycle length
linger_tout <time>	linger on socket close
nagle <bool>	use Nagle alg
xact_think <time>	pause on xaction start
pconn_use_lmt <int>	number of requests on a single connection
goal <int>	total completions
file_scan <poll|select>	system call to use for scanning ready files
fake_hosts <list>	use given addresses, do not lookup real interfaces
idle_tout <list>	exit after inactivity timeout
rng_seed <int>	general purpose seed
unique_world <bool>	use URL set that is unique across runs
origin <addr>	origin host
proxy <addr>	proxy host
abs_urls <bool>	generate absolute urls
ports <port_range>	use explicit port binding
conn_pool <int>	[initial] connection pool capacity
conn_pool_dyn <bool>	dynamically adjust the size of a conn pool
launch_win <time>	interval to start all robots
cool_phase <time>	minimal cool-off phase duration
robots <int>	number of robots
req_rate <rate>	robot request rate
maximize_req_rate <bool>	adjust req_rate run-time to find maximum
ign_bad_cont_tags <bool>	ignore bad content tags
ign_false_hits <bool>	ignore false hits
prn_false_misses <bool>	dump rep headers of false misses
do_ios <bool>	do socket ios
world_type <str>	part of a URL
world_id <str>	part of a URL
world_urls <file>	file with URLs
unique_urls <int>	append unique suffix (counter) to URLs
recur <ratio>	recurrence (prob of revisiting a URL)
order <int>	request order
rep_cachable <ratio>	portion of cachable replies
dhr <ratio>	document hit ratio
pop_model <model>	popularity model
tmp_loc <distr>	distances distr for temporal locality
tmp_loc_delta <int>	fuzziness of temporal locality choices
tmp_loc_depth <int>	max depth of tmp locality plan
prefilled_cnt <int>	number of already cached oids

Verb_lvl specifies how much info will be printed to the console. Normally, level zero will have only a couple of lines per run. Level one will allow for interval and phase stats to be printed. A negative level will disable any output.

Most errors are reported with level zero.

Regardless of verb_lvl setting, all console messages are duplicated in the log.

The --dump option controls what messages and what parts of messages should be printed on the console. Possible message types are: req[uest], rep[ly], and err[or]. Possible message parts are hdr (for ``header'') and body. Dumping of message bodies is not supported at the time of writing.

For example, to dump all request headers, one may use:

polysrv --dump req-hdr

To dump the headers of all requests and the headers of erroneous messages, use:

polyclt --dump req-hdr,err-hdr

Finally, to dump everything about errors, consider:

polyclt --dump err

and to dump all headers, use:

polyclt --dump hdr

Note that sometimes Polygraph does not have the required data at the time of dump. Polygraph will try to at least provide some meta information about the message then.

If a message part matches both negative (error) and positive (reply or request) type masks, the part may be printed twice.

This option obsoletes --prn_reqs, --prn_reps and --prn_errs options.

When prn_reqs is set, Poly will print the request line and HTTP headers of each request. The requests are dumped to standard output.

Note that the output will not be logged.

This mode is very useful both for debugging benchmarking setup and for understanding Poly traffic model.

When prn_reps is set, Poly will print the status line and HTTP headers of each reply. See --prn_reqs option for details.

When prn_errs is set, Polygraph will attempt to dump the status/request line and HTTP headers of each message that led to a xactions error. For some errors, a part of a message content is also printed. See --prn_reqs option for details.

The label option allows you to assign a string label to a run. The label gets logged (as any other option value) and is also included into notification messages (see --notify). The latter is useful if you running several experiments and want polymon to distinguish them by a short ``name''.

Note that notification messages truncate labels to 15 characters, and polymon usually displays 6 first characters.

Polygraph determines the maximum level of available file descriptors using getrlimit(RLIMIT_NOFILE) system call. It then attempts to set the current level to that maximum using the setrlimit(RLIMIT_NOFILE) system call. The return value of the latter (actually about 97% of it) is then used as a Polygraph internal FD limit.

Polygraph will not attempt to create more TCP sockets than its internal limit. However, some OSes are known to be unhappy when a process is close to the limit. In a non-production benchmarking environment, there may be also a competition for file descriptors with other processes. The fd_limit option can be used to lower the internal limit even further.

Polygraph will quit if it reaches its internal FD limit. In most cases, the log (if enabled using the --log option) will be flushed/saved before program termination.

One cannot raise the FD limit using the fd_limit option! The original limit is reported by the operating system and must be changed first. Different OSes will require different techniques for raising the file descriptor limits. Some well-known hacks can be found elsewhere.

Finally, note that two Polygraph header files (src/include/config.h and src/xstd/include/xstd.h are #defining FD_SETSIZE to be 4096. If you intend to use more file descriptors, you probably should increase that value. FD_SETSIZE is a system ``constant'' that is used for select(2) related calls on some OSes.

The --config option specifies configuration file for polygraph clients and/or servers. See Polygraph Language documentation for details on how to write a configuration file.

Root configuration file as well as #include files are searched for using the --cfg_dirs option.

The --config option specifies the list of directories that are searched for root configuration file as well as #include files. See --config option for how to specify a root configuration file. See Polygraph Language documentation for details on #include statements and how to write a configuration file.

Console option allows you to redirect console output into a file. The file must be reachable from the current directory.

This option enables preserving detailed stats in a log file.

All log content is kept in memory until the end of a run. This option allows you to specify the maximum log buffer size to hold that info. When logging module runs out of buffer space, it stops logging completely.

Logging must be enabled with the --log option first. If no --log option was specified, a small 10KB log is kept in memory and is discarded at the end of a run.

Polygraph versions 1.0p5 and earlier will exit when run out of log buffer space. These versions are using memory resident log buffer regardless of the --log option presence.

Stats_cycle specifies the duration of Interval stats cycle. Shorter cycles give more precise statistics but result in larger binary logs.

Nagle is an equivalent of the TCP_NODELAY protocol option. See Unix Socket FAQ for more info.

Xact_think specifies the ``think time'' for each transaction.

On the server side, a transaction will sleep right after a connection is accepted and before reading the request.

On the client side, a transaction will sleep right before opening a connection and sending a request.

When first created, an HTTP connection is assigned the number of transactions it should be used for. That number is drawn from the distribution specified using the pconn_use_lmt option. A usage limit of 2 transactions or more implies a persistent connection (if the other side cooperates).

Pconn_use_lmt makes sense on both server and client sides. By default, all connections are used only once.

Poly-client or poly-server will close a connection if either the other side has sent ``Connection: close'' header or the connection usage limit has been reached. ``Proxy-Connection:'' headers are also honored. Polygraph indicates its intention to keep or close a connection by sending the appropriate Connection:'' header with every request.

Note: The Nagle algorithm may need to be turned off using the --nagle option. Otherwise, TCP ack packets are delayed for about 200msec resulting in 5req/sec throughput for a single TCP connection.

Use the goal option to specify the termination conditions for an experiment. A termination condition can be experiment duration, number of successful transactions, or number of errors. At least one condition must be specified. Conditions are ORed together.

The order of conditions is flexible. The following simple heuristics are used to guess the actual order:

1. first number if any is ``number of successful transactions''
2. second number if any is ``number of errors''
3. time if any is ``experiment duration''

Conditions are separated with a column (:). For example:

polyclt --goal -1:1hour:1000 ...

would mean to stop an experiment in 1 hour or after 1000 errors. The number of successful transactions is unlimited.

Note that goal settings are also used to determine the termination condition for experiment phases.

Poly does not yet support termination based on number of xaction errors.

The origin address is used to connect directly to the origin server when no --proxy option is given. The absence of the --proxy option implies direct connection and causes generation of ``relative'' URLs (i.e., URLs without an http://host:port prefix).

The origin address is always copied to the Host: HTTP header.

If the port value is 80, it is not included in URLs, but is included in Host: headers.

In Poly 1.0, the host part of an address is not interpreted. Earlier versions of Polygraph used the --proxy option to determine the actual destination of a request. See also --abs_urls option for generating ``relative'' URLs in Poly 1.0.

If --proxy option is given, Polygraph assumes proxied connection and generates absolute URLs (i.e., URLs with am http://host:port prefix). The requests are sent to the specified proxy address. See also --origin option.

The host part of the address must be an IP address; FQDNs are not yet supported.

In Poly 1.0, all requests are sent to the address specified in the proxy option. To send requests directly to Polyclient, use Polyclient's address. See also --abs_urls option for generating ``relative'' URLs in Poly 1.0.

This option is obsolete, see --origin option. The old description is left below for users of Poly 1.0.

By default, Polygraph client will generate absolute URLs. Relative URLs (i.e., URLs without the http://host:port part) are useful for testing transparent proxies.

The affect of specifying relative URLs (--abs_urls no) can be illustrated by the following example:

        http://host:port/whatever        --- absolute URL
        /http:/host:port/whatever        --- relative URL

Disabling absolute URLs have no effect on HTTP headers.

The conn_pool option activates the Connection Pool. The value of the option is the [initial] size of the pool. See also the --conn_pool_dyn option.

The conn_pool_dyn option allows the Connection Pool to grow and shrink on-demand.

All Robots are started within the specified ``launch window''. The actual starts are uniformly distributed in [0, launch_win) interval.

When the number of robots is large, starting them at the same time may cause staggering behavior with many transactions effectively ``synchronized''. Specify an appropriate non-zero launch_win to avoid that.

The cool_phase option specifies the duration of a cool-off phase.

Cool-off phase is usually very short or nonexistent. However, there are cases when it is required to continue to generate traffic some time after the measurement phase. For example, a presence of a cool-off phase helps when several clients are executed concurrently and one want to guarantee that all measurement phases will stop before any of the clients quits.

The robots option specifies the number of concurrent Robots to simulate.

The req_rate option tells Polyclient to emit HTTP requests at a constant rate. Each Robot will submit requests at a given rate without waiting for responses from the server.

The workload is modeled using Poisson streams. In other words, requests inter-submission times are distributed exponentially.

This option is currently mutually exclusive with the --xact_think option.

The maximize_req_rate option enables ``maximum request rate'' searching mode. The option must be used together with the --req_rate option which specifies initial rate. The search is done by incrementing or decrementing actual request rate depending on the reply rate. Verbose level of 4 or higher will display some run-time information about the algorithm at decision points.

Support for this mode is rudimental, and more work is needed.

Setting do_ios to ``no'', will disable most I/O operations on sockets. The latter may be useful in conjunction with the --prn_reqs option to get a request stream dump without a running server.

Support for this option is experimental.

The world_type option can be used to modify the world_type part of generated URLs.

World_id specifies the world_id part of generated URLs.

A special value of `unique' can be used to instruct Poly to generate a unique string (which is also the default behavior).

World Ids are often used to prevent (or ensure) overlapping of the requested URLs between runs.

World_cap specifies the number of unique Objects in the simulated World.

Note: Starting Polygraph version 2.1.0, recurrence is specified on per-robot basis using PGL.

Recurrence ratio specifies the probability that a URL is revisited by a Robot. Assuming ideal proxy scenario, revisit to a URL results in a ``hit'' iff the corresponding object is cachable.

Note that robots do not know cachability status of the objects they request which makes it impossible to specify Document Hit Ratio as a stand-alone parameter. However, if cachable objects have the same popularity as uncachable ones, DHR can be computed as recurrence ratio divided by cachability ratio. Thus, you can select recurrence to give you a desired hit ratio.

Recurrence ratio is a part of the popularity model. That model is undergoing significant renovation at the time of writing.

When a positive order is specified, Polyclient will pre-generate all Object Ids using some default order and then permutate the generated set. Thus, one is guaranteed that the same set of Object Ids will be used for all experiments that differ only in order settings.

This option is handy for simulating a hit-only workload: All ``passes'' are done with a --unique_urls option and different values of --order option. The first ``pass'' will have all misses. Consecutive passes will have high hit ratios.

The value of 1 is likely to correspond to the order of Object Ids when --order is not specified. However, this behavior may change in the future.

The rep_cachable option specifies the portion of cachable replies (not unique Object Ids!) as seen on the client side.

A cachable reply will include

	Cache-Control: public,max-age=31536000
	Expires: a date about one year from ``now''

while an uncachable reply will have

	Cache-Control: private,no-cache
	Pragma: no-cache

Cachability is determined at random. However, the objects (identified by their Object Ids), preserve their status across accesses. In other words, ``once [un]cachable, always [un]cachable''. The status may be preserved across experiments as long as the value of the rep_cachable option and other traffic parameters stay the same, but we are not positive.

The rep_cachable option was moved from Polyserver to Polyclient in 1.0p4.

The dhr determines document (object) hit ratio. Hit Ratio Model keeps he ratio stable regardless of other traffic conditions if at all possible.

The ratio is calculated as if an ideal proxy is in use. Hence, the request stream (in terms of hit ratio) does not depend on the actual proxy under test.

A proxy may decide not to cache some of the cachable replies, and it may delete old cachable replies. These and perhaps other proxy actions may lead to a smaller measured hit ratio compared to the offered ratio.

Pop_model selects the Object Popularity Model to use and allows to specify model parameters if any.

The tmp_loc option specifies an inter-request distance distribution to use with the Temporal Reference Locality Model. If a special none distribution is specified, the Temporal Locality Model is disabled and has no effect on traffic generation.

A number of research studies suggested that using lognormal distribution for inter-request distances is appropriate for Web traffic.

Note that inter-request distances are measured in requests, not time units. Thus, no scale factor should be specified for distribution parameters.

The Temporal Reference Locality Model selects one or more candidate slots for the next request to an Object Id. The selected slots are centered around the slot chosen by the locality distribution (see --tmp_loc). The tmp_loc_delta option specifies how many slots to the left and right of the chosen position are to be included in the selection.

For example, a tmp_loc_delta value of 0 means that a selection will include only one slot (the chosen one). A tmp_loc_delta value of 1 will include 3 slots (including the chosen one) into a selection.

Tmp_loc_delta value is also used to select the best Object Id to request next among the first 2*Tmp_loc_delta slots.

To disable temporal locality module, do not use negative tmp_loc_deltas, use none for --tmp_loc_delta instead.

To support Temporal Reference Locality, Polyclt keeps a schedule or plan of Object Ids to be requested. The tmp_loc_depth option can be used to explicitly specify the plan ``capacity'' or ``depth''.

As a rule of thumb, tmp_loc_depth should be close to the maximum request distance Temporal Locality Model can generate.