1PMLOGSUMMARY(1) General Commands Manual PMLOGSUMMARY(1)
2
6 pmlogsummary - calculate averages of metrics stored in a set of PCP ar‐
7 chives
8
10 pmlogsummary [-abfFHiIlmMNsvxyz] [-B nbins] [-n pmnsfile] [-p preci‐
11 sion] [-S starttime] [-T endtime] [-Z timezone] archive [metricname
12 ...]
13
15 pmlogsummary prints statistical information about metrics of numeric
16 type contained within the files of a set of Performance Co-Pilot (PCP)
17 archive logs. The default output prints time averages for both counter
18 and non-counter metrics. The set of archive logs is identified by ar‐
19 chive, which is a comma-separated list of names, each of which may be
20 the base name of an archive or the name of a directory containing one
21 or more archives. The archive logs are typically created using pmlog‐
22 ger(1).
23 The metrics of interest are named in the metricname arguments. If met‐
25 ricname is a non-leaf node in the Performance Metrics Name Space
26 (pmns(5)), then pmlogsummary will recursively descend the PMNS and
27 report on all leaf nodes. If no metricname argument is given, the root
28 of the namespace is used.
29 Normally pmlogsummary operates on the default pmns(5), however if the
31 -n option is specified an alternative namespace is loaded from the file
32 pmnsfile.
33 The command line options -S and -T can be used to specify a time window
35 over which metrics should be summarized. These options are common to
36 most Performance Co-Pilot tools and are fully described in PCPIntro(1).
37 The remaining options control the specific information to be reported.
39 Metrics with counter semantics are converted to rates before being
40 evaluated.
41 -a Print all information. This is equivalent to -blmMy.
43 -b Print both forms of averaging, that is both stochastic and time
45 averaging.
46 -B Print the approximate distribution of values, using histogram
48 bins such that the value range (minimum - maximum) for each met‐
49 ric is divided equally into nbins bins, and each bin accumulates
50 the frequency of observed values in the corresponding range.
51 Refer to the ``OUTPUT FORMAT'' section below for a description
52 of how the distribution of values is reported).
53 -f Spreadsheet format - the tab character is used to delimit each
55 field printed. This option is intended to allow pmlogsummary
56 output to be imported directly into common spreadsheet applica‐
57 tions.
58 -F Spreadsheet format - the comma character is used to delimit each
60 field printed. This option is intended to allow pmlogsummary
61 output to be imported directly into common spreadsheet applica‐
62 tions which support the Comma Separated Value (.csv) format.
63 -H Print a one-line header at the start showing what each field
65 represents.
66 -l Also print the archive label, showing the log format version,
68 the time and date for the start and end of the archive time win‐
69 dow, and the host from which the performance metrics values were
70 collected.
71 -i Also print the time at which the minimum value was logged. The
73 format of this timestamp is described in the ``OUTPUT FORMAT''
74 section below.
75 -I Also print the time at which the maximum value was logged. The
77 format of this timestamp is described in the ``OUTPUT FORMAT''
78 section below.
79 -m Also print the minimum logged value for each metric.
81 -M Also print the maximum logged value for each metric.
83 -s Print (only) the sum of all logged values for each metric.
85 -N Suppress any warnings resulting from individual archive fetches
87 (default).
88 -p Print all floating point numbers with precision digits after the
90 decimal place.
91 -v Report (verbosely) on warnings resulting from individual archive
93 fetches.
94 -x Print stochastic averages instead of the default (time aver‐
96 ages).
97 -y Also print the number of samples encountered in the set of ar‐
99 chives for each metric.
100 By default, pmlogsummary reports the time of day according to the local
102 timezone on the system where pmlogsummary is run. The -Z option
103 changes the timezone to timezone in the format of the environment vari‐
104 able TZ as described in environ(7). The -z option changes the timezone
105 to the local timezone at the host that is the source of the performance
106 metrics, as specified in the label record of the archive log.
107
109 The pmlogsummary output format is spartan as it is intended to be post-
110 processed with standard tools. This means that there is no annotation
111 associated with each output field which would make processing harder.
112 The intention is that pmlogsummary output be massaged into a format
113 which can be used by a spreadsheet program, is suitable for inclusion
114 in a web page, or whatever.
115 For each metric, pmlogsummary produces a single output line as follows:
117 metricname value(s) units
119 For metrics with multiple instances, pmlogsummary produces multiple
121 lines of output as follows:
122 metricname ["instance 1"] value(s) units
124 metricname ["instance 2"] value(s) units
125 metricname ["instance N"] value(s) units
126 The printed value(s) for each metric always follow this order: stochas‐
128 tic average, time average, minimum, minimum timestamp, maximum, maximum
129 timestamp, count, [bin 1 range], bin 1 count, ... [bin nbins range],
130 bin nbins count. The individual values for each metric are space-sepa‐
131 rated (unless the -f option is used).
132 All counter metrics which are measured in units of time will be con‐
134 verted to seconds before being rate converted and used in the pmlogsum‐
135 mary calculations. The values calculated for these metrics are also
136 printed in seconds.
137 The units will be displayed in the format described by pmUnitsStr(3).
139 Given either of the -i or -I options, pmlogsummary produces two differ‐
141 ent timestamp formats, depending on the interval over which it is run.
142 For an interval greater than 24 hours, the date is displayed in addi‐
143 tion to the time at which the maxima and/or minima occurred. If the
144 extent of the data being checked is less than 24 hours, a more precise
145 format is used (time is displayed with millisecond precision, but with‐
146 out the date).
147
149 The average for an individual metric is calculated as follows:
150 Non-counter metrics are averaged using stochastic averaging - each
152 observation has an equal weighting towards the calculation of the aver‐
153 age (the sum of all values divided by the total number of values, for
154 each metric).
155 Counter metrics are averaged using time averaging (by default), but the
157 -x option can be used to specify that counters be averaged using the
158 stochastic method instead. When calculating a time average, the sum of
159 the product of each sample value multiplied by the time difference
160 between each sample, is divided by the total time over which that met‐
161 ric was logged.
162 Counter metrics whose measurements do not span 90% of the set of ar‐
164 chives will be printed with the metric name prefixed by an asterisk
165 (*).
166
168 $ pmlogsummary -aN -p 1 -B 3 surf network.interface.out.bytes
169 Log Label (Log Format Version 1)
170 Performance metrics from host www.sgi.com
171 commencing Tue Jan 14 20:50:50.317 1997
172 ending Wed Jan 29 10:13:07.387 1997
173 network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7 \
174 1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7] \
175 17 byte / sec
176 network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
177 1033 [] 0 [] 0 byte / sec
178 network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
179 1033 [] 0 [] 0 byte / sec
180 network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031 \
181 [<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec
182 A description of each field in the first line of statistical output,
184 which describes one instance of the network.interface.out.bytes metric,
185 follows:
186 ┌──────────────┬───────────────────────────────────────────┐
188 │ Field │ Meaning │
189 ├──────────────┼───────────────────────────────────────────┤
190 │["xpi0"] │ instance name │
191 │202831.3 │ stochastic average │
192 │202062.5 │ time average │
193 │20618.7 │ minimum value │
194 │1235067.7 │ maximum value │
195 │971 │ total number of values for this instance │
196 │[<=425435.0] │ range for first bin (20618.7-425435.0) │
197 │912 │ number of values in first bin │
198 │[<=830251.4] │ range for second bin (425435.0-830251.4) │
199 │42 │ number of values in second bin │
200 │[<=1235067.7] │ range for third bin (830251.4-1235067.7) │
201 │17 │ number of values in third bin │
202 │byte / sec │ base units for this metric │
203 └──────────────┴───────────────────────────────────────────┘
205 $PCP_VAR_DIR/pmns/*
206 default PMNS specification files
207 $PCP_LOG_DIR/pmlogger/hostname
208 Default directory for PCP archives containing performance
209 metric values collected from the host hostname.
210
212 Environment variables with the prefix PCP_ are used to parameterize the
213 file and directory names used by PCP. On each installation, the file
214 /etc/pcp.conf contains the local values for these variables. The
215 $PCP_CONF variable may be used to specify an alternative configuration
216 file, as described in pcp.conf(5).
217
219 PCPIntro(1), pmchart(1), pmdumptext(1), pmlogextract(1), pmlogger(1),
220 pmrep(1), pmval(1), PMAPI(3), pmUnitsStr(3) and pmns(5).
221
223 All are generated on standard error and are intended to be self-
224 explanatory.
225Performance Co-Pilot PCP PMLOGSUMMARY(1)