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

NAME

6       pmdumptext - dump performance metrics to an ASCII table
7

SYNOPSIS

9       pmdumptext [-CFGHilmMNoruVXz?]  [-a archive] [-A align] [-c config] [-d
10       delimiter] [-f format] [-h host] [-n pmnsfile] [-O offset]  [-P  preci‐
11       sion]  [-R lines] [-s sample] [-S starttime] [-t interval] [-T endtime]
12       [-U string] [-w width] [-Z timezone] [metric ...]
13

DESCRIPTION

15       pmdumptext outputs the values of performance metrics collected live  or
16       from  a  set  of  Performance Co-Pilot (PCP) archives.  By default, the
17       metric values are displayed in tab separated  columns,  prefixed  by  a
18       timestamp.
19
20       Unless  directed  to  another  host by the -h option, or to one or more
21       sets of archives by the -a option, or an explict host: or archive/ pre‐
22       fix  in  the  metric  (see below for more information), pmdumptext will
23       contact the Performance Metrics Collector Daemon (PMCD)  on  the  local
24       host to obtain the required information.
25
26       pmdumptext may be run in interactive mode with the -i option which dis‐
27       plays the values in equal width columns.  Without this option,  no  at‐
28       tempt  is  made  to line up any values allowing the output to be easily
29       parsed by other applications.
30
31       The format of the output can be further controlled by changing the pre‐
32       cision of the values with -P, the width of the columns with -w, and the
33       format of the values with the -G and -F options  for  the  shortest  of
34       scientific or fixed digits, and a fixed width format, respectively.
35
36       By  default  pmdumptext will scale metric values to ``canonical'' units
37       of bytes, seconds and counts.  The one exception is with the -r  option
38       where  the  values  are not scaled.  The -u option reports the units of
39       each metric.
40
41       The metrics to be dumped can be listed on the command line, in a config
42       file,  or  piped  to  pmdumptext on stdin.  A metric consists of an op‐
43       tional source (host or archive), the metric name, and an  optional  in‐
44       stance  list immediately after the name.  A colon is used to separate a
45       host name from the metric, and a forward slash (``/'') to  separate  an
46       archive  name from the metric.  Instances are enclosed in square brack‐
47       ets and a comma is used between each  instance  if  more  than  one  is
48       stated.  For example, some legal metrics are:
49
50               kernel.all.cpu.idle
51               myhost:kernel.all.cpu.idle[cpu0,cpu3]
52               /path/to/myarchive/kernel.all.cpu.idle[cpu1]
53
54       When  a  metric does not contain a host: or archive/ prefix, e.g.  ker‐
55       nel.all.cpu.idle above, then the source of the metric is determined  by
56       the following rules:
57       (a) PMCD on host from the -h option if any, else
58       (b) the archive from the first -a option if any, else
59       (c) the  host from the first metric prior to this one with a host: pre‐
60           fix if any, else
61       (d) the archive from the first metric prior to this  one  with  an  ar‐
62           chive/ prefix if any, else
63       (e) PMCD on the local host, which is equivalent to local::metric.
64
65       The  format of a metric is further described in PCPIntro(1) in the PER‐
66       FORMANCE METRIC SPECIFICATIONS section.  A normalization value may  op‐
67       tionally follow a metric name in a config file or on stdin.  The metric
68       value will be scaled by this value.  For example, if  the  file  system
69       ``/dev/root''  has  a capacity of 1965437 bytes, then the percentage of
70       the file system that is used could be dumped with this config:
71
72               filesys.used[/dev/root] 19654.37
73
74       A normalization value may not be used with metrics specified as command
75       line arguments.
76
77       A metric name is not required to be a leaf node in the Performance Met‐
78       rics Name Space (PMNS), except when one or more  instances  are  speci‐
79       fied.   For  example,  to dump all file system metrics, only filesys is
80       required to dump filesys.capacity, filesys.used, filesys.free etc.
81

OPTIONS

83       The command line options -A (or --align),  -O  (or  --origin),  -S  (or
84       --start)  and -T (or --finish) control the alignment, offset, start and
85       end time when visualizing metrics from  archives.   These  options  are
86       common  to  most  Performance Co-Pilot tools and are fully described in
87       PCPIntro(1).
88
89       The other available options are:
90
91       -a archive, --archive=archive
92            Specifies the historical archive from which  metrics  can  be  ob‐
93            tained  for a particular host.  archive is the full path to an in‐
94            dividual archive file, or the name of a directory  containing  ar‐
95            chives,  or the basename of an archive - all previously created by
96            pmlogger(1).  Multiple sets of archives (separated by commas or in
97            different  -a options) from different hosts may be given, but only
98            one set of archives per host is permitted.  Any metrics  that  are
99            not  associated with a specific host or archive will use the first
100            archive as their source.
101
102       -c config, --config=config
103            If no metrics are listed on the command line, a config file can be
104            used to specify the metrics to be dumped.  Unlike the command line
105            metrics, each metric may be followed  by  a  normalization  value.
106            Empty lines and lines that begin with ``#'' are ignored.
107
108       -C, --check
109            Exit  before  dumping  any  values, but after parsing the metrics.
110            Metrics, instances, normals and units are listed  if  -m,  -l,  -N
111            and/or -u are specified.
112
113       -d delimiter, --delimiter=delimiter
114            Specify  the  delimiter that separates each column of output.  The
115            delimiter may only be a single character.
116
117       -f format, --time-format=format
118            Use the format string for formatting the timestamp with  each  set
119            of  values.   The  syntax  of  this string is the same as that de‐
120            scribed in strftime(3).  An empty format string (eg. '') will  re‐
121            move the timestamps from the output.
122
123       -F, --fixed
124            Output  the values in a fixed width format of 6 characters.  Posi‐
125            tive numbers are represented as dd.ddu  and  negative  numbers  as
126            [-]d.ddu.   The  postfix  multiplier  may have the values K(10^3),
127            M(10^6), G(10^9) and T(10^12).  For example, 4567  would  be  dis‐
128            played as 4.57K, even if the units of the metric are bytes.
129
130       -G, --scientific
131            Output  the  values using the shortest of a scientific format or a
132            decimal notation.
133
134       -h host, --host=host
135            Fetch performance metrics from pmcd(1) on host,  rather  than  the
136            default localhost.
137
138       -H, --headers
139            Show all headers before dumping any metric values.  This is equiv‐
140            alent to -lmNu.
141
142       -i, --interactive
143            Output the data in fixed width columns using  fixed  width  values
144            (see  -F)  so  that  it is human-readable.  This option may not be
145            used with -P as fixed point values are not fixed width.  This  op‐
146            tion  will also affect the output of -m and -u options as the met‐
147            ric, instance and unit names will be truncated.
148
149       -l, --source
150            Show the source of the metrics.  In interactive mode, the host  of
151            the  metrics is shown.  In non-interactive mode, this option shows
152            the source of the metrics with the metric name even if -m  is  not
153            specified.
154
155       -m, --metrics
156            Output  the metric names before the metric values.  The source and
157            units of the metrics may also be dumped with the -l and -u options
158            respectively.   If  in  interactive mode, the metrics names may be
159            truncated, and the instance names, where relevant, are also  trun‐
160            cated on the follow line.
161
162       -M   Output  the column number and complete metric names before dumping
163            any values.  If the -l flag is also specified, the source  of  the
164            metrics is also shown.
165
166       -n pmnsfile, --namespace=pmnsfile
167            Load an alternative local PMNS from the file pmnsfile.
168
169       -o, --offset
170            When  a  timestamp  is  being reported (ie. unless an empty format
171            string is given with the -f option),  the  timestamp  is  prefixed
172            with  the  offset in seconds from the start of the set of archives
173            or the beginning of the execution of pmdumptext.
174
175       -N   Output the normalization factors before the metric values.
176
177       -p precision, --precision=precision
178            Set the precision of the values.  This option may not be used with
179            -F as the precision is constant.  The default precision is 3.
180
181       -r, --raw
182            Output the raw metric values, do not convert counters to rates and
183            do not scale values to  ``canonical''  units.   This  option  also
184            causes pmdumptext to ignore the normalization values for each met‐
185            ric.
186
187       -R lines, --repeat=lines
188            Repeat the header every lines of output.  This option is useful in
189            interactive mode when using a graphical window to avoid the header
190            scrolling beyond the window's buffer, and to realign the header if
191            the window is resized.
192
193       -s samples, --samples=samples
194            pmdumptext will terminate after this many samples.
195
196       -t interval, --interval=interval
197            The  interval  option follows the syntax described in PCPIntro(1),
198            and in the simplest form may be an unsigned integer  (the  implied
199            units  in  this case are seconds).  The default interval is 1 sec‐
200            ond.
201
202       -u, --units
203            Output the units of the metrics before the first values, but after
204            the metric names if -m is also specified.
205
206       -U string, --unavailable=string
207            Change  the output when values are unavailable to string.  The de‐
208            fault string is ``?''.
209
210       -V, --version
211            Display version number and exit.
212
213       -w width, --widthfR=width
214            Set the column width of the output.  Strings will be truncated  to
215            this width, and maybe postfixed by ``...'' if the width is greater
216            than 5.
217
218       -X, --extended
219            Output the column number and complete metric names,  one-per-line,
220            both  before  dumping  the first set of values and again each time
221            the header is repeated.
222
223       -z, --hostzone
224            Use the local timezone of the host that is the source of the  per‐
225            formance  metrics,  as identified by either the -h or the first -a
226            options.  The default is to use the timezone of the local host.
227
228       -Z timezone, --timezone=timezone
229            Use timezone for the date and time.  Timezone is in the format  of
230            the environment variable TZ as described in environ(7).
231
232       -?, --help
233            Display usage message and exit.
234

MULTIPLE SOURCES

236       pmdumptext  supports  the dumping of metrics from multiple hosts or set
237       of archives.  The metrics listed on the command line or in  the  config
238       file may have no specific source or come from different sources.
239
240       However,  restrictions apply when archives are specified on the command
241       line (-a) and/or in the configuration file.  Firstly, there may be only
242       one  set of archives for any one host.  Secondly, the hosts of any met‐
243       rics with host sources must correspond to the host  of  a  set  of  ar‐
244       chives,  either  on the command line or previously as the source of an‐
245       other metric.
246
247       The options -a and -h may not be used together.
248

UNIT CONVERSION

250       All metrics that have the semantics of counters are automatically  con‐
251       verted  to  rates  over the sample time interval.  In interactive mode,
252       pmdumptext will also change the units of some metrics so that they  are
253       easier to comprehend:
254
255       o      All  metrics with space units (bytes to terabytes) are scaled to
256              bytes.  Note that 1024 bytes with be represented as  1.02K,  not
257              1.00K.
258
259       o      Metrics that are counters with time units (nanoseconds to hours)
260              represent time utilization over the sample interval.   The  unit
261              strings  of  such  metrics is changed to ``Time Utilization'' or
262              abbreviated to ``util'' and the values  are  normalized  to  the
263              range zero to one.
264

EXAMPLES

266       o To examine the load on two hosts foo and bar, simultaneously:
267
268     $ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
269                  Source        foo     bar
270     Wed Jul 30 11:37:53      0.309   0.409
271     Wed Jul 30 11:37:54      0.309   0.409
272     Wed Jul 30 11:37:55      0.309   0.409
273
274       o  To output the memory utilization on a remote host called bong with a
275       simpler timestamp:
276
277     $ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
278       Metric        kernel  fs_ctl  _dirty  _clean    free    user
279        Units             b       b       b       b       b       b
280     09:32:28         8.98M   0.97M   0.00    3.90M   7.13M  46.13M
281     09:32:29         8.99M   0.98M   0.00    5.71M   5.39M  46.03M
282     09:32:30         8.99M   1.07M   0.00    5.81M   4.55M  46.69M
283     09:32:31         9.03M   1.16M   0.00    6.45M   3.48M  47.00M
284     09:32:32         9.09M   1.18M  20.48K   6.23M   3.29M  47.30M
285
286       o To dump all metrics collected in an archive at a 30  second  interval
287       to a file for processing by another tool:
288
289     $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
290

FILES

292       $PCP_VAR_DIR/pmns/*
293            default PMNS specification files
294

PCP ENVIRONMENT

296       Environment variables with the prefix PCP_ are used to parameterize the
297       file and directory names used by PCP.  On each installation,  the  file
298       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
299       $PCP_CONF variable may be used to specify an alternative  configuration
300       file, as described in pcp.conf(5).
301
302       For environment variables affecting PCP tools, see pmGetOptions(3).
303

SEE ALSO

305       PCPIntro(1),  pmcd(1),  pmchart(1),  pmlogger(1),  pmrep(1),  PMAPI(3),
306       strftime(3) and environ(7).
307
308
309
310Performance Co-Pilot                  SGI                        PMDUMPTEXT(1)
Impressum