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 [-abfFHiIlmMNsvVxyz?] [-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 Metrics with counter semantics are converted to rates before being
31 evaluated.
32
34 The available command line options are:
35 -a, --all
37 Print all information. This is equivalent to -blmMy.
38 -b Print both forms of averaging, that is both stochastic and time
40 averaging.
41 -B nbins, --bins=nbins
43 Print the approximate distribution of values, using histogram bins
44 such that the value range (minimum - maximum) for each metric is
45 divided equally into nbins bins, and each bin accumulates the fre‐
46 quency of observed values in the corresponding range. Refer to
47 the ``OUTPUT FORMAT'' section below for a description of how the
48 distribution of values is reported).
49 -f Spreadsheet format - the tab character is used to delimit each
51 field printed. This option is intended to allow pmlogsummary out‐
52 put to be imported directly into common spreadsheet applications.
53 -F Spreadsheet format - the comma character is used to delimit each
55 field printed. This option is intended to allow pmlogsummary out‐
56 put to be imported directly into common spreadsheet applications
57 which support the Comma Separated Value (.csv) format.
58 -H, --header
60 Print a one-line header at the start showing what each field rep‐
61 resents.
62 -i, --mintime
64 Also print the time at which the minimum value was logged. The
65 format of this timestamp is described in the ``OUTPUT FORMAT''
66 section below.
67 -I, --maxtime
69 Also print the time at which the maximum value was logged. The
70 format of this timestamp is described in the ``OUTPUT FORMAT''
71 section below.
72 -l, --label
74 Also print the archive label, showing the log format version, the
75 time and date for the start and end of the archive time window,
76 and the host from which the performance metrics values were col‐
77 lected.
78 -m, --minimum
80 Also print the minimum logged value for each metric.
81 -M, --maximum
83 Also print the maximum logged value for each metric.
84 -n pmnsfile, --namespace=pmnsfile
86 Load an alternative Performance Metrics Name Space (PMNS(5)) from
87 the file pmnsfile.
88 -N Suppress any warnings resulting from individual archive fetches
90 (default).
91 -p precision, --precision=precision
93 Print all floating point numbers with precision digits after the
94 decimal place.
95 -s, --sum
97 Print (only) the sum of all logged values for each metric.
98 -S starttime, --start=starttime
100 Set the starttime of the time window. Refer to PCPIntro(1) for a
101 complete description of the syntax for starttime.
102 -T endtime, --finish=endtime
104 Set the endtime of the time window. Refer to PCPIntro(1) for a
105 complete description of the syntax for endtime.
106 -v, --verbose
108 Report (verbosely) on warnings resulting from individual archive
109 fetches.
110 -V, --version
112 Display version number and exit.
113 -x Print stochastic averages instead of the default (time averages).
115 -y, --samples
117 Also print the number of samples encountered in the set of ar‐
118 chives for each metric.
119 -z, --hostzone
121 Change the timezone to the local timezone at the host that is the
122 source of the performance metrics, as specified in the label
123 record of the archive log.
124 -Z timezone, --timezone=timezone
126 By default, pmlogsummary reports the time of day according to the
127 local timezone on the system where pmlogsummary is run. Change
128 the timezone to timezone in the format of the environment variable
129 TZ as described in environ(7).
130 -?, --help
132 Display usage message and exit.
133
135 The pmlogsummary output format is spartan as it is intended to be post-
136 processed with standard tools. This means that there is no annotation
137 associated with each output field which would make processing harder.
138 The intention is that pmlogsummary output be massaged into a format
139 which can be used by a spreadsheet program, is suitable for inclusion
140 in a web page, or whatever.
141 For each metric, pmlogsummary produces a single output line as follows:
143 metricname value(s) units
145 For metrics with multiple instances, pmlogsummary produces multiple
147 lines of output as follows:
148 metricname ["instance 1"] value(s) units
150 metricname ["instance 2"] value(s) units
151 metricname ["instance N"] value(s) units
152 The printed value(s) for each metric always follow this order: stochas‐
154 tic average, time average, minimum, minimum timestamp, maximum, maximum
155 timestamp, count, [bin 1 range], bin 1 count, ... [bin nbins range],
156 bin nbins count. The individual values for each metric are space-sepa‐
157 rated (unless the -f option is used).
158 All counter metrics which are measured in units of time will be con‐
160 verted to seconds before being rate converted and used in the pmlogsum‐
161 mary calculations. The values calculated for these metrics are also
162 printed in seconds.
163 The units will be displayed in the format described by pmUnitsStr(3).
165 Given either of the -i or -I options, pmlogsummary produces two differ‐
167 ent timestamp formats, depending on the interval over which it is run.
168 For an interval greater than 24 hours, the date is displayed in addi‐
169 tion to the time at which the maxima and/or minima occurred. If the
170 extent of the data being checked is less than 24 hours, a more precise
171 format is used (time is displayed with millisecond precision, but with‐
172 out the date).
173
175 The average for an individual metric is calculated as follows:
176 Non-counter metrics are averaged using stochastic averaging - each
178 observation has an equal weighting towards the calculation of the aver‐
179 age (the sum of all values divided by the total number of values, for
180 each metric).
181 Counter metrics are averaged using time averaging (by default), but the
183 -x option can be used to specify that counters be averaged using the
184 stochastic method instead. When calculating a time average, the sum of
185 the product of each sample value multiplied by the time difference
186 between each sample, is divided by the total time over which that met‐
187 ric was logged.
188 Counter metrics whose measurements do not span 90% of the set of ar‐
190 chives will be printed with the metric name prefixed by an asterisk
191 (*).
192
194 $ pmlogsummary -aN -p 1 -B 3 surf network.interface.out.bytes
195 Log Label (Log Format Version 1)
196 Performance metrics from host www.sgi.com
197 commencing Tue Jan 14 20:50:50.317 1997
198 ending Wed Jan 29 10:13:07.387 1997
199 network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7 \
200 1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7] \
201 17 byte / sec
202 network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
203 1033 [] 0 [] 0 byte / sec
204 network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
205 1033 [] 0 [] 0 byte / sec
206 network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031 \
207 [<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec
208 A description of each field in the first line of statistical output,
210 which describes one instance of the network.interface.out.bytes metric,
211 follows:
212 ┌──────────────┬───────────────────────────────────────────┐
214 │ Field │ Meaning │
215 ├──────────────┼───────────────────────────────────────────┤
216 │["xpi0"] │ instance name │
217 │202831.3 │ stochastic average │
218 │202062.5 │ time average │
219 │20618.7 │ minimum value │
220 │1235067.7 │ maximum value │
221 │971 │ total number of values for this instance │
222 │[<=425435.0] │ range for first bin (20618.7-425435.0) │
223 │912 │ number of values in first bin │
224 │[<=830251.4] │ range for second bin (425435.0-830251.4) │
225 │42 │ number of values in second bin │
226 │[<=1235067.7] │ range for third bin (830251.4-1235067.7) │
227 │17 │ number of values in third bin │
228 │byte / sec │ base units for this metric │
229 └──────────────┴───────────────────────────────────────────┘
231 All are generated on standard error and are intended to be self-
232 explanatory.
233
235 $PCP_VAR_DIR/pmns/*
236 default PMNS specification files
237 $PCP_LOG_DIR/pmlogger/<hostname>
239 Default directory for PCP archives containing performance metric
240 values collected from the host <hostname>.
241
243 Environment variables with the prefix PCP_ are used to parameterize the
244 file and directory names used by PCP. On each installation, the file
245 /etc/pcp.conf contains the local values for these variables. The
246 $PCP_CONF variable may be used to specify an alternative configuration
247 file, as described in pcp.conf(5).
248
250 PCPIntro(1), pmchart(1), pmdumptext(1), pmlogextract(1), pmlogger(1),
251 pmrep(1), pmval(1), PMAPI(3), pmUnitsStr(3) and PMNS(5).
252Performance Co-Pilot PCP PMLOGSUMMARY(1)