PMWTF(1) General Commands Manual PMWTF(1)NAME
pmwtf - compares archives and report significant differences
SYNOPSIS
pmwtf [-dz] [-p precision] [-q thres] [-S starttime] [-T endtime] [-B starttime] [-E endtime] [-x metric] [-X file] [-Z timezone] archive1
[archive2]
DESCRIPTION
pmwtf compares the average values for every metric in either one or two archives, in a given time window, for changes that are likely to be
of interest when searching for performance regressions.
The archive log has the base name archive and must have been previously created using pmlogger(1). The pmlogsummary(1) utility is used to
obtain the average values used for comparison.
There are two sorts of invocation of the tool: with either one or two archives.
In the first case, the only sensible command line requires use of all four time window arguments. These are specified using the same time
window format described in PCPIntro(1), and are -S and -T for the start and end times of the first time window of interest in the archive,
and -B and -E for the start and end times of the second time window of interest.
In the second case, with two archives, the -B and -E options might be unnecessary. This might be the case, for example, when comparing the
same time window of two consecutive days (usually two separate archives), or a time window on the same day of different weeks.
In either case, pmwtf produces a sorted summary of those metrics in the specified window whose values have deviated the most from a minimal
threshold. The level of deviation is calculated by dividing the average value of each metric in both logs, and then calculating whether
the ratio falls outside of a range considered normal. This ratio can be adjusted using the -q option, and by default it is 2 (i.e. report
all metrics with average values that have more than doubled in the two time windows or more than halved in the two time windows).
Should any metrics be present in one window but missing from the other, a diagnostic will be displayed listing each missing metric and the
archive from which it was missing.
The remaining options control the specific information to be reported. Metrics with counter semantics are converted to rates before being
evaluated.
-p Print all floating point numbers with precision digits after the decimal place.
-x Compare each metric in each archive in the time windows specified to a given egrep(1) pattern, excluding those that match from the
report output.
-X Allows a file to be specified which containing egrep(1) patterns which are applied to the metric names to optionally exclude some from
the report.
-z Use the local timezone from the given archives.
-Z Changes the timezone in the archive labels to timezone in the format of the environment variable TZ as described in environ(5).
FILES
$PCP_LOG_DIR/pmlogger/hostname
Default directory for PCP archives containing performance metric values collected from the host hostname.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the
file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configura-
tion file, as described in pcp.conf(5).
SEE ALSO PCPIntro(1), pmlogger(1), pmlogsummary(1), egrep(1), pcp.conf(5) and pcp.env(5).
Performance Co-Pilot PCP PMWTF(1)
Check Out this Related Man Page
PMLOGSUMMARY(1) General Commands Manual PMLOGSUMMARY(1)NAME
pmlogsummary - calculate averages of metrics stored in a PCP archive
SYNOPSIS
pmlogsummary [-abfFHiIlmMNsvxyz] [-B nbins] [-n pmnsfile] [-p precision] [-S starttime] [-T endtime] [-Z timezone] archive [metricname ...]
DESCRIPTION
pmlogsummary prints statistical information about metrics of numeric type contained within the files of a Performance Co-Pilot (PCP) ar-
chive log. The default output prints time averages for both counter and non-counter metrics. The archive log has the base name archive,
typically created using pmlogger(1).
The metrics of interest are named in the metricname arguments. If metricname is a non-leaf node in the Performance Metrics Name Space
(pmns(5)), then pmlogsummary will recursively descend the PMNS and report on all leaf nodes. If no metricname argument is given, the root
of the namespace is used.
Normally pmlogsummary operates on the default pmns(5), however if the -n option is specified an alternative namespace is loaded from the
file pmnsfile.
The command line options -S and -T can be used to specify a time window over which metrics should be summarized. These options are common
to most Performance Co-Pilot tools and are fully described in PCPIntro(1).
The remaining options control the specific information to be reported. Metrics with counter semantics are converted to rates before being
evaluated.
-a Print all information. This is equivalent to -blmMy.
-b Print both forms of averaging, that is both stochastic and time averaging.
-B Print the approximate distribution of values, using histogram bins such that the value range (minimum - maximum) for each metric is
divided equally into nbins bins, and each bin accumulates the frequency of observed values in the corresponding range. Refer to the
``OUTPUT FORMAT'' section below for a description of how the distribution of values is reported).
-f Spreadsheet format - the tab character is used to delimit each field printed. This option is intended to allow pmlogsummary output
to be imported directly into common spreadsheet applications.
-F Spreadsheet format - the comma character is used to delimit each field printed. This option is intended to allow pmlogsummary out-
put to be imported directly into common spreadsheet applications which support the Comma Separated Value (.csv) format.
-H Print a one-line header at the start showing what each field represents.
-l Also print the archive label, showing the log format version, the time and date for the start and (current) end of the archive time
window, and the host from which the performance metrics values were collected.
-i Also print the time at which the minimum value was logged. The format of this timestamp is described in the ``OUTPUT FORMAT'' sec-
tion below.
-I Also print the time at which the maximum value was logged. The format of this timestamp is described in the ``OUTPUT FORMAT'' sec-
tion below.
-m Also print the minimum logged value for each metric.
-M Also print the maximum logged value for each metric.
-s Print (only) the sum of all logged values for each metric.
-N Suppress any warnings resulting from individual archive fetches (default).
-p Print all floating point numbers with precision digits after the decimal place.
-v Report (verbosely) on warnings resulting from individual archive fetches.
-x Print stochastic averages instead of the default (time averages).
-y Also print the number of samples encountered in the archive for each metric.
By default, pmlogsummary reports the time of day according to the local timezone on the system where pmlogsummary is run. The -Z option
changes the timezone to timezone in the format of the environment variable TZ as described in environ(5). The -z option changes the time-
zone to the local timezone at the host that is the source of the performance metrics, as specified in the label record of the archive log.
OUTPUT FORMAT
The pmlogsummary output format is spartan as it is intended to be post-processed with standard tools. This means that there is no annota-
tion associated with each output field which would make processing harder. The intention is that pmlogsummary output be massaged into a
format which can be used by a spreadsheet program, is suitable for inclusion in a web page, or whatever.
For each metric, pmlogsummary produces a single output line as follows:
metricname value(s) units
For metrics with multiple instances, pmlogsummary produces multiple lines of output as follows:
metricname ["instance 1"] value(s) units
metricname ["instance 2"] value(s) units
metricname ["instance N"] value(s) units
The printed value(s) for each metric always follow this order: stochastic average, time average, minimum, minimum timestamp, maximum, maxi-
mum timestamp, count, [bin 1 range], bin 1 count, ... [bin nbins range], bin nbins count. The individual values for each metric are space-
separated (unless the -f option is used).
All counter metrics which are measured in units of time will be converted to seconds before being rate converted and used in the pmlogsum-
mary calculations. The values calculated for these metrics are also printed in seconds.
The units will be displayed in the format described by pmUnitsStr(3).
Given either of the -i or -I options, pmlogsummary produces two different timestamp formats, depending on the interval over which it is
run. For an interval greater than 24 hours, the date is displayed in addition to the time at which the maxima and/or minima occurred. If
the extent of the data being checked is less than 24 hours, a more precise format is used (time is displayed with millisecond precision,
but without the date).
NOTES
The average for an individual metric is calculated as follows:
Non-counter metrics are averaged using stochastic averaging - each observation has an equal weighting towards the calculation of the aver-
age (the sum of all values divided by the total number of values, for each metric).
Counter metrics are averaged using time averaging (by default), but the -x option can be used to specify that counters be averaged using
the stochastic method instead. When calculating a time average, the sum of the product of each sample value multiplied by the time differ-
ence between each sample, is divided by the total time over which that metric was logged.
Counter metrics whose measurements do not span 90% of the archive will be printed with the metric name prefixed by an asterisk (*).
EXAMPLE
$ pmlogsummary -aN -p 1 -B 3 surf network.interface.out.bytes
Log Label (Log Format Version 1)
Performance metrics from host www.sgi.com
commencing Tue Jan 14 20:50:50.317 1997
ending Wed Jan 29 10:13:07.387 1997
network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7
1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7]
17 byte / sec
network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0]
1033 [] 0 [] 0 byte / sec
network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0]
1033 [] 0 [] 0 byte / sec
network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031
[<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec
A description of each field in the first line of statistical output, which describes one instance of the network.interface.out.bytes met-
ric, follows:
+--------------+-------------------------------------------+
| Field | Meaning |
+--------------+-------------------------------------------+
|["xpi0"] | instance name |
|202831.3 | stochastic average |
|202062.5 | time average |
|20618.7 | minimum value |
|1235067.7 | maximum value |
|971 | total number of values for this instance |
|[<=425435.0] | range for first bin (20618.7-425435.0) |
|912 | number of values in first bin |
|[<=830251.4] | range for second bin (425435.0-830251.4) |
|42 | number of values in second bin |
|[<=1235067.7] | range for third bin (830251.4-1235067.7) |
|17 | number of values in third bin |
|byte / sec | base units for this metric |
+--------------+-------------------------------------------+
FILES
$PCP_VAR_DIR/pmns/*
default PMNS specification files
$PCP_LOG_DIR/pmlogger/hostname
Default directory for PCP archives containing performance metric values collected from the host hostname.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the
file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configura-
tion file, as described in pcp.conf(5).
SEE ALSO PCPIntro(1), pmchart(1), pmdumptext(1), pmlogextract(1), pmlogger(1), pmval(1), PMAPI(3), pmUnitsStr(3) and pmns(5).
DIAGNOSTICS
All are generated on standard error and are intended to be self- explanatory.
Performance Co-Pilot PCP PMLOGSUMMARY(1)