1PMLOGSUMMARY(1)             General Commands Manual            PMLOGSUMMARY(1)
2
3
4

NAME

6       pmlogsummary - calculate averages of metrics stored in a set of PCP ar‐
7       chives
8

SYNOPSIS

10       pmlogsummary [-abfFHiIlmMNsvVxyz?]  [-B nbins] [-n pmnsfile] [-p preci‐
11       sion]  [-S  starttime]  [-T  endtime] [-Z timezone] archive [metricname
12       ...]
13

DESCRIPTION

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
24       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
30       Metrics  with  counter  semantics  are  converted to rates before being
31       evaluated.
32

OPTIONS

34       The available command line options are:
35
36       -a, --all
37            Print all information.  This is equivalent to -blmMy.
38
39       -b   Print both forms of averaging, that is both  stochastic  and  time
40            averaging.
41
42       -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
50       -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
54       -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
59       -H, --header
60            Print  a one-line header at the start showing what each field rep‐
61            resents.
62
63       -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
68       -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
73       -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
79       -m, --minimum
80            Also print the minimum logged value for each metric.
81
82       -M, --maximum
83            Also print the maximum logged value for each metric.
84
85       -n pmnsfile, --namespace=pmnsfile
86            Load  an alternative Performance Metrics Name Space (PMNS(5)) from
87            the file pmnsfile.
88
89       -N   Suppress any warnings resulting from  individual  archive  fetches
90            (default).
91
92       -p precision, --precision=precision
93            Print  all  floating point numbers with precision digits after the
94            decimal place.
95
96       -s, --sum
97            Print (only) the sum of all logged values for each metric.
98
99       -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
103       -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
107       -v, --verbose
108            Report (verbosely) on warnings resulting from  individual  archive
109            fetches.
110
111       -V, --version
112            Display version number and exit.
113
114       -x   Print stochastic averages instead of the default (time averages).
115
116       -y, --samples
117            Also  print  the  number  of samples encountered in the set of ar‐
118            chives for each metric.
119
120       -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
125       -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
131       -?, --help
132            Display usage message and exit.
133

OUTPUT FORMAT

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
142       For each metric, pmlogsummary produces a single output line as follows:
143
144          metricname  value(s) units
145
146       For metrics with multiple  instances,  pmlogsummary  produces  multiple
147       lines of output as follows:
148
149          metricname ["instance 1"] value(s) units
150          metricname ["instance 2"] value(s) units
151          metricname ["instance N"] value(s) units
152
153       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
159       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
164       The units will be displayed in the format described by pmUnitsStr(3).
165
166       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

NOTES

175       The average for an individual metric is calculated as follows:
176
177       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
182       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
189       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

EXAMPLES

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
209       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
213             ┌──────────────┬───────────────────────────────────────────┐
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             └──────────────┴───────────────────────────────────────────┘

DIAGNOSTICS

231       All are generated on standard  error  and  are  intended  to  be  self-
232       explanatory.
233

FILES

235       $PCP_VAR_DIR/pmns/*
236            default PMNS specification files
237
238       $PCP_LOG_DIR/pmlogger/<hostname>
239            Default  directory  for PCP archives containing performance metric
240            values collected from the host <hostname>.
241

PCP ENVIRONMENT

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

SEE ALSO

250       PCPIntro(1), pmchart(1), pmdumptext(1),  pmlogextract(1),  pmlogger(1),
251       pmrep(1), pmval(1), PMAPI(3), pmUnitsStr(3) and PMNS(5).
252
253
254
255Performance Co-Pilot                  PCP                      PMLOGSUMMARY(1)
Impressum