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) archive 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 output 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 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 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 timezone 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.
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
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 average (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 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 statistical output, which
describes one instance of the network.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/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 configuration
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.