NAME
pmlogsummary - calculate averages of metrics stored in a
PCP archive
SYNOPSIS
pmlogsummary [-abfFiIlmMNxyz] [-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 Perfor
mance Co-Pilot (PCP) archive log. The default output
prints time averages for both counter and non-counter met
rics. The archive log has the base name archive, typi
cally created using pmlogger(1).
The metrics of interest are named in the metricname argu
ments. If metricname is a non-leaf node in the Perfor
mance Metrics Name Space (pmns(4)), then pmlogsummary will
recursively descend the PMNS and report on all leaf nodes.
If no metricname argument is given, the root of the names
pace is used.
Normally pmlogsummary operates on the default pmns(4),
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).
delimit each field printed. This option is
intended to allow pmlogsummary output to be
imported directly into common spreadsheet applica
tions.
-F Spreadsheet format - the comma character is used to
delimit each field printed. This option is
intended to allow pmlogsummary output to be
imported directly into common spreadsheet applica
tions which support the Comma Separated Value
(.csv) format.
-l Also print the archive label, showing the log for
mat 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'' section below.
-I Also print the time at which the maximum value was
logged. The format of this timestamp is described
in the ``OUTPUT FORMAT'' section below.
-m Also print the minimum logged value for each met
ric.
-M Also print the maximum logged value for each met
ric.
-N Suppress any warnings resulting from individual
archive fetches.
-p Print all floating point numbers with precision
digits after the decimal place.
-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 timezone to the
local timezone at the host that is the source of the per
formance metrics, as specified in the label record of the
archive log.
The pmlogsummary output format is spartan as it is
intended to be post-processed with standard tools. This
means that there is no annotation 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, maximum 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 pmlogsummary calculations. The values
calculated for these metrics are also printed in seconds.
The units will be displayed in the format described by
pmUnitStr(3).
Given either of the -i or -I options, pmlogsummary pro
duces 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 mil
lisecond precision, but without the date).
NOTES
The average for an individual metric is calculated as fol
lows:
Non-counter metrics are averaged using stochastic averag
ing - each observation has an equal weighting towards the
calculation of the average (the sum of all values divided
by the total number of values, for each metric).
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 difference
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 statisti
cal output, which describes one instance of the net
work.interface.out.bytes metric, 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/pmloggerhostname
Default directory for PCP archives containing
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 configuration file,
as described in pcp.conf(4).
SEE ALSO
PCPIntro(1), pmdumptext(1), pmlogextract(1), pmlogger(1),
pmval(1), PMAPI(3), pmUnitStr(3) and pmns(4).
DIAGNOSTICS
All are generated on standard error and are intended to be
self- explanatory.
Man(1) output converted with
man2html