Lx documentation has been synchronized with Poly 2.1.0.

The description of lx output is available elsewhere

Lx is the primary tool for extracting statistics from binary log files created by Polygraph. Lx can also accumulate or join stats from several log files before reporting statistics. The latter feature is essential for experiments with many clients or servers.

Lx was introduced in Poly 1.0p6.

usage: lx [--option ...] <log_file_name> ...
options:

help	list of options
out <file>	redirect console output
phase <str>	phase name
objects <str>	names of objects to extract
trace <time>	print (averaged at specified intervals) run-time stats (rather than totals)
prn_time <bool>	print relative [to start] time as the first column
prn_rep_cnt <bool>	prepend lines with number of replies received since log start
prn_names <bool>	prepend object values with object names

Polygraph collects statistics in phases. The phase option selects which portion of the log will be analyzed by lx.

Prior to Polygraph 2.0.0, there was a fixed number of phases: ``warm'', ``meas'', and ``cold''. Only the measurement phase contained useful information.

Later versions of Polygraph allow for unlimited number of phases (with custom names, durations, load levels, etc.).

Polygraph logs store a lot of information. Lx calls a self-contained piece of info an object. Objects may be as simple as a single integer number and as complex as a distribution histogram.

The objects options accepts a list of comma-separated object names. Some objects have parameters (e.g., 50-th percentile). The parameters must be separated from an object name with a column (':').

Below is a list of objects available via lx. The list is sorted by object name.

All

Simply a synonym for all objects that do not require parameters.

Note that `All' macro used to be called all in Polygraph 1.x.

class_rptm_mean

Mean response time for a given class. See resp_tm_vs_class object for more detailed output.

This object requires a parameter, the actual class group to inspect. For example, `resp_tm_perc:N_chb_miss' extracts mean response time of cachable misses on a persistent connection (second or later transaction on a single connection). Use the resp_tm_vs_class object for a list of supported classes/groups.

conn_close_act_use_hist

Conn_close_act_use_hist is a histogram of number of transactions per connection restricted to connections closed by Polygraph immediately after last use. See other conn_close_ histograms for idle persistent connections stats.

conn_close_act_ttl_hist

Conn_close_act_ttl_hist is a histogram of total connection life time (time-to-live) restricted to connections closed by Polygraph immediately after their last use. See other conn_close_ histograms for idle persistent connections stats.

conn_close_frgn_use_hist

Conn_close_frgn_use_hist is a histogram of number of transactions per connection restricted to idle persistent connections closed by the other (foreign) side. This histogram may help in detecting a proxy limit on the number of request per persistent connection.

conn_close_frgn_ttl_hist

Conn_close_frgn_ttl_hist is a histogram of total connection life time (time-to-live) restricted to idle persistent connections closed by the other (foreign) side. This histogram may help in detecting a proxy limit on the duration a persistent connection can stay open.

conn_close_lcl_use_hist

Conn_close_lcl_use_hist is a histogram of number of transactions per connection restricted to idle persistent connections closed by Polygraph. This histogram helps in double checking Polygraph limit on the number of request per persistent connection.

conn_close_lcl_ttl_hist

Conn_close_lcl_ttl_hist is a histogram of total connection life time (time-to-live) restricted to idle persistent connections closed by Polygraph. This histogram helps in double checking Polygraph limit on the duration a persistent connection can stay open.

conn_ttl_mean

`Conn_ttl_mean' holds mean connection life time. In the absence of persistent connections, this object value will be closed to `resp_tm_mean'. However, `conn_ttl_mean' includes failed connections, while `resp_tm_mean' does not.

conn_ttl_vs_use

This object prints connection life time versus the number of transactions per connection.

conn_use_hist

`conn_use_hist' is a distribution of the number of transactions per connection. Values higher than one correspond to persistent connections.

conn_use_mean

`conn_use_mean' stands for the mean number of transactions per connection. Usually, mean values higher than one indicate the presence of persistent connections.

err_cnt

The number of errors detected during the given phase.

Error accounting in Polygraph needs more work. Be careful when interpreting this value and double check with error messages recorded during the experiment.

err_cnt_tbl

A table with per-type breakout of error messages.

The mapping between the errno value (an integer that gets logged run-time) and the corresponding error message (a string extracted from your environment during lx execution) is somewhat machine dependent. Thus, while the error counts will always be correct, the message strings may be wrong if you move the log around.

See also err_cnt above.

err_pct

Portion of failed transaction, in percents. See err_cnt above.

log_cnt

This object is not extracted from a binary log. `Log_cnt' stores the number of log files merged by lx during the current execution.

`Log_cnt' is handy if you want to know the average request rate or similar characteristics per client or server (i.e., per log file). Note that most values produced by lx are sums of corresponding values in each log file.

phase_name

Holds name(s) of phase(s) that contributed to statistics collection. See --phase option.

req_bhr

Offered byte hit ratio. See req_dhr object below and the --dhr option.

The ratio is reported in percents.

Versions 1.0 of Poly do not report valid ratios for traffic exceeding 2GB.

req_dhr

Offered document hit ratio. See the --dhr option.

The ratio is reported in percents.

req_rate

Offered request rate for Constant Request Rate workloads. See the --req_rate option for more info.

rep_bhr

Measured byte hit ratio, in percents.

Versions 1.0 of Poly do not report valid ratios for traffic exceeding 2GB.

rep_dhr

Measured document hit ratio, in percents.

rep_bcr

Measured byte cachability ratio. That is, the portion of cumulative size of all cachable replies as seen by the client side. All replies are counted.

rep_dcr

Measured document cachability ratio. That is, the portion of cachable replies as seen by the client side. All replies are counted.

rep_rate

Measured reply (response) rate, in replies per second.

rep_sz_hist

Reply (response) size histogram. Reply size includes HTTP headers.

rep_sz_mean

Mean reply (response) size. Reply size includes HTTP headers.

resp_tm_hist

This object holds the entire xaction response time distribution. It will print the distribution as a table with a header. The table is not nicely formatted, but easy to parse in scripts. Time measurements are in milliseconds.

`Resp_tm_hist' is handy to plot response time CDFs.

Polygraph verisons prior to 2.x used `resp_tm_' prefix for all response time related objects.

rptm_mean

Mean xaction response time, in milliseconds. To get the entire distribution, use the `rptm_hist' object.

rptm_mean:hit and rptm_mean:miss are supported starting with Polygraph 1.3.2.

Polygraph verisons prior to 2.x used resp_tm_ prefix for all response time related objects.

resp_tm_perc

`Resp_tm_perc' holds a single percentile value within xaction response time distribution. The returned value is measured in milliseconds.

This object requires a parameter, the actual percentile to extract. For example, `resp_tm_perc:50' extracts median response time (50-th percentile).

Polygraph verisons prior to 2.x used resp_tm_ prefix for all response time related objects.

resp_tm_vs_class

`Resp_tm_vs_class' shows the dependency between the ``class'' of an object and reply response time. The following classes are available:

Short Name	Full Name	Description
miss	miss	valid reply came from a server (possibly through a proxy)
hit	hit	valid reply came from a proxy rather than a server
chb	cachable	a cachable reply
unc	uncachable	an uncachable reply
1	non-persistent connection	a connection was closed after serving at most one transaction
N	persistent connection	a connection carried more than one transaction

Use short names with lx.

Classes may intersect (e.g. a cachable miss on a persistent connection).

Object ``classes'' are not yet supported in Poly 2.x.

resp_tm_vs_sz

`Resp_tm_vs_sz' object holds response time percentiles for major reply size ranges. It is handy to analyze the dependencies between response time and the amount of data transferred. In theory, larger responses should take more time to transfer. In practice, various buffers and bugs often lead to more interesting dependencies than linear growth. Also, the affect of reply size may depend on the proxy load.

Polygraph verisons prior to 2.x used resp_tm_ prefix for all response time related objects.

soread_sz_hist

`soread_sz_hist' histogram holds sizes of individual socket read(2) system calls.

sowrite_sz_hist

`sowrite_sz_hist' histogram holds sizes of individual socket write(2) system calls.

wait.level.mean

wait.level.mean is an average number of waiting transactions. The only reason for a transaction to enter a ``wait'' state is the lack of available connections due to a open_conn_lmt limit in the Robot configuration.

Many standard workloads have positive open_conn_lmt limits (to simulate browsers behavior) and non-zero wait.level.mean readings. If the waiting queue grows or exceeds the number of active transactions (see xact.level.mean), then the test most likely should be considered a failure even if no errors or warnings are immediately visible.

A Robot that never drains its wait queue becomes a best-effort Robot. When queues grow, polyclt processes will sooner or later run out of memory and die.

xact.level.mean

xact.level.mean is an average number of active transactions. A transaction is considered to be active if it is not waiting. See the wait.level.mean object for more information.

Name:	--trace
Type:	time
Default:	no default
Version:	1.2.2 and up

By default, each object value is averaged over the specified phase. The trace option allows you to see how the value was changing with time. Traceable stats are averaged at specified intervals. Detailed, small scale analysis is often essential in detecting performance problems that are not detectable using large scale averages.

Not all object values can be computed in the middle of a log. Those values that can, will be printed; others will be silently ignored.

When multiple log files are specified, the log files are not ``joined'' when trace mode is on!

Note: --trace was called --prn_trace in Polygraph versions prior to 2.0.0. It had a boolean type back then.

If enabled, the prn_time option causes lx to print timestamps as the first column of the output. The timestamps are in seconds and are relative to log start.

The prn_time option is especially useful together with the trace option.

If enabled, the prn_rep_cnt option causes lx to print number of replies received since log start as the first column of the output.

The prn_rep_cnt option is especially useful together with the trace option.

The prn_rep_cnt option can be combined with the prn_time option. If used together, timestamps are printed first followed by the reply count.