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