This page explains some of the Poly terminology and describes some of the objects used by Polygraph. Documentation has been synchronized with Poly 1.x.

Connection Pool

Polygraph may keep a pool of TCP connections in various states. If Pool size is positive, a special logical thread will try to keep the total number of pooled connections close to the pool size. The latter is achieved by pre-opening connections (i.e., issuing non-blocking connect(2) calls without an explicit request from a Robot.

Connection Pool size can be either dynamic or static. If --conn_pool_dyn is on, Polygraph will adjust the pool size trying to get the total number of established connections just right to meet robots' demands. Otherwise, Polygraph tries to keep a constant number of pending and established connections, regardless of the demand.

Specifying a static pool size smaller than the number of robots is probably useless as it is likely to have no effect (as if the pool was disabled).

Connection Pool is enabled using the --conn_pool option.

Console

Polygraph sends status and error messages to the console. Console output can be redirected into a file using the --console option. The amount of information is controoled using the --verb_lvl option.

All messages that can go to the console (they may or may not be addmitted based on the current verbosity level) are also logged.

Request and reply dumps are not send to the console but are rather printed to the standard output stream. Errors that are not caught by polygraph are dumped to the standard error stream. Standard streams are also redirected, but are not logged. This behavior may change in the future versions of Polygraph.

Exsessive printing to the Console during a production test is a bad idea as it is likely to affect performance.

Console output format is documented elsewhere.

Interval Stats

Statistics collected during relatively short, constant ``size'' intervals. (compare with phase stats).

There are two types of statistical intervals:

• Time based: statistics is dumped and reset approximately every second (when there is other activity). It can be identified on the console by the i- prefix, followed by the phase name at the time of a dump.
• Xaction based: statistics is dumped and reset every 1000 transactions. It uses the x- prefix, followed by the phase name at the time of a dump. Xaction based stats are not yet supported.

Interval stats are totally independent from ``phase stats'' and may span several phases.

Interval stats are printed with verbosity level of 2 and higher.

Log

All statistical measurements, console output, and some house-keeping info are ``logged''. Logging in Polygraph has two stages. First, all information is accumulated in a memory buffer. The size of the buffer is determined by the --log_size option. If Polygraph runs out of logging space during an experiment, it either exits (versions 1.0p5 and earlier) or stops logging.

Second, at the end of the experiment, the memory resident buffer can be logged into a file specified by the --log option. Otherwise, the information is lost.

Polylog is a machine-independent binary file. The lr and lx programs can be used to access the contents of a log.

If you do not mind occasional garbage on the screen, Unix strings routine is handy for extracting console output from a binary log.

Phase

There are three phases in an experiment life cycle:

1. Warm-up phase: robots are being started. Measurements are usually imprecise because the system has not reached a steady state. The warm-up phase lasts at least 10% of a goal and does not terminate until all robots start sending requests.
2. Measurement phase: robots are ``working''. Measurements collected during this phase are usually reported as experiments ``results''. The measurement phase lasts about 90% of a goal. No robot can quit during this phase.
3. Cool-off phase: robots are being stopped. This phase is usually very short. Currently, pending transactions are not guaranteed to finish nicely.

Each phase collects and logs its own measurements.

Phase Stats are totally independent from interval stats and usually last many intervals.

On the server side, the --goal option is optional. If it is not specified, the warm-up phase never ends.

Phase Stats

Statistics collected during one of three phases. These stats are dumped to the console with a p- prefix, followed by the phase name.

Phase stats are totally independent from interval stats and usually last many intervals.

Phase stats are printed with verbosity level of 1 and higher.

Robot

Robot (a.k.a. ``user'' or ``client'') is the main logical thread of execution in Polyclient. Robots submit requests and receive replies. The frequency and nature of the submissions depends on the workload and is controlled by options like --req_rate. The number of robots is controlled by the --robots option.

Robots are usually independent from each other in their actions, but they share command line options. In other words, most options will apply to all robots.

Transaction

On the client side, transaction (a.k.a. ``xaction'') is a sequence of sending a request and receiving a reply for that request. On the server side, transaction is a sequence of receiving a request and sending a reply for that request.

URL structure

Polygraph generates URLs in one of the following formats:

• 'http://' host ':' port '/_' object_id '/' world_id '/' world_type

• 'http://' host ':' port '/_' object_id '/' world_id '/' world_type '/' unique_id

• 'http://' host ':' port pre-loaded_url

The first format is the default. If the --unique_urls option is specified, unique_ids are appended to URLs (second format). With the --world_urls option, one can make Polygraph to use URLs pre-loaded from a file (third format).

The host and port components are taken from the --origin option. Default HTTP port (80) will not show up in a URL.

An Object Id identifies the server ``resource'' or object specified by the URL. Object sizes and some processing delays stay the same for a given Object Id regardless of the number of times that Id is requested.

World_id and world_type components are controlled by the corresponding command line options, --world_id and --world_type. They do not have any special meaning for Polygraph, but are essential for separating traffic between consecutive experiments.

To simulate URLs with no protocol and host name parts, use --abs_urls (required for testing transparent proxies).

One can see what URLs are being generated using the --prn_reqs option on client or server side.

World

Polygraph's ``world'' is a collection of Objects. Objects are identified by their Ids. The maximum world capacity (i.e., number of unique Object Ids) is at most 2147483647 or 2^31-1.

During a simulation, Polygraph decides which objects to request based on target hit ratio, request order and other factors. See Traffic Model description for details.

The World also has several attributes like like World Type or World Id. See URL structure for information on their use.