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