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

NAME

6       pmdumptext - dump performance metrics to an ASCII table
7

SYNOPSIS

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

DESCRIPTION

15       pmdumptext outputs the values of performance metrics collected live  or
16       from a Performance Co-Pilot (PCP) archive.  By default, the metric val‐
17       ues are displayed in tab separated columns, prefixed by a timestamp.
18
19       Unless directed to another host by the -h option, or to one or more ar‐
20       chives  by  the -a option, pmdumptext will contact pmcd(1) on the local
21       host to obtain the required information.
22
23       pmdumptext may be run in interactive mode with the -i option which dis‐
24       plays  the  values  in  equal  width  columns.  Without this option, no
25       attempt is made to line up any values allowing the output to be  easily
26       parsed by other applications.
27
28       The format of the output can be further controlled by changing the pre‐
29       cision of the values with -P, the width of the columns with -w, and the
30       format  of  the  values  with the -G and -F options for the shortest of
31       scientific or fixed digits, and a fixed width format, respectively.
32
33       The metrics to be dumped can be listed on the command line, in a config
34       file,  or  piped  to  pmdumptext  on  stdin.   A  metric consists of an
35       optional source (host or archive), the metric  name,  and  an  optional
36       instance  list immediately after the name.  A colon is used to separate
37       a host name from the metric, and a forward slash (``/'') to separate an
38       archive  name from the metric.  Instances are enclosed in square brack‐
39       ets and a comma is used between each  instance  if  more  than  one  is
40       stated.  For example, some legal metrics are:
41
42               kernel.all.cpu.idle
43               myhost:kernel.all.cpu.idle[cpu0,cpu3]
44               /path/to/myarchive/kernel.all.cpu.idle[cpu1]
45
46       The  format of a metric is further described in PCPIntro(1).  A normal‐
47       ization value may optionally follow a metric name in a config  file  or
48       on stdin.  The metric value will be scaled by this value.  For example,
49       if the file system ``/dev/root'' has a capacity of 1965437 bytes,  then
50       the  percentage  of  the  file system that is used could be dumped with
51       this config:
52
53               filesys.used[/dev/root] 19654.37
54
55       A normalization value may not be used with metrics specified as command
56       line arguments.
57
58       A metric name is not required to be a leaf node in the Performance Met‐
59       rics Name Space (PMNS), except when one or more  instances  are  speci‐
60       fied.   For  example,  to dump all file system metrics, only filesys is
61       required to dump filesys.capacity, filesys.used, filesys.free etc.
62

COMMAND LINE OPTIONS

64       The command line options -A, -O, -S and -T control the alignment,  off‐
65       set,  start and end time when visualizing metrics from archives.  These
66       options are common to most Performance Co-Pilot  tools  and  are  fully
67       described in PCPIntro(1).
68
69       The other available options are:
70
71       -a     Specify an archive from which metrics can be obtained for a par‐
72              ticular host.  archive is the basename of an archive, previously
73              created  by pmlogger(1).  Multiple archives (separated by commas
74              or in different -a options) from different hosts may  be  given,
75              but  only  one  per host is permitted.  Any metrics that are not
76              associated with a specific host or archive will  use  the  first
77              archive as their source.
78
79       -C     Exit  before  dumping any values, but after parsing the metrics.
80              Metrics, instances, normals and units are listed if -m,  -l,  -N
81              and/or -u are specified.
82
83       -c     If  no metrics are listed on the command line, a config file can
84              be used to specify the metrics to be dumped.  Unlike the command
85              line  metrics,  each  metric  may be followed by a normalization
86              value.  Empty lines and lines that begin with ``#'' are ignored.
87
88       -d     Specify the delimiter that separates each column of output.  The
89              delimiter may only be a single character.
90
91       -f     Use the format string for formatting the timestamp with each set
92              of values.  The syntax of  this  string  is  the  same  as  that
93              described  in strftime(3).  An empty format string (eg. '') will
94              remove the timestamps from the output.
95
96       -F     Output the values in a fixed width format of 6 characters.  Pos‐
97              itive  numbers are represented as dd.ddu and negative numbers as
98              [-]d.ddu.  The postfix multiplier may have the  values  K(10^3),
99              M(10^6),  G(10^9) and T(10^12).  For example, 4567 would be dis‐
100              played as 4.57K, even if the units of the metric are bytes.
101
102       -G     Output the values using the shortest of a scientific format or a
103              decimal notation.
104
105       -h     Fetch  performance metrics from pmcd(1) on host, rather than the
106              default localhost.
107
108       -H     Show all headers before dumping  any  metric  values.   This  is
109              equivalent to -lmNu.
110
111       -i     Output  the data in fixed width columns using fixed width values
112              (see -F) so that it is human-readable.  This option may  not  be
113              used  with  -P  as fixed point values are not fixed width.  This
114              option will also affect the output of -m and -u options  as  the
115              metric, instance and unit names will be truncated.
116
117       -l     Show  the  source of the metrics.  In interactive mode, the host
118              of the metrics is shown.  In non-interactive mode,  this  option
119              shows  the source of the metrics with the metric name even if -m
120              is not specified.
121
122       -m     Output the metric names before the metric  values.   The  source
123              and  units  of the metrics may also be dumped with the -l and -u
124              options respectively.  If in interactive mode, the metrics names
125              may  be  truncated,  and the instance names, where relevant, are
126              also truncated on the follow line.
127
128       -M     Output the column number and complete metric names before  dump‐
129              ing any values.  If the -l flag is also specified, the source of
130              the metrics is also shown.
131
132       -n     Load an alternative local PMNS from the file pmnsfile.
133
134       -o     When a timestamp is being reported (ie. unless an  empty  format
135              string  is  given with the -f option), the timestamp is prefixed
136              with the offset in seconds from the start of the archive or  the
137              beginning of the execution of pmdumptext.
138
139       -N     Output the normalization factors before the metric values.
140
141       -P     Set  the  precision  of the values.  This option may not be used
142              with -F as the precision is constant.  The default precision  is
143              3.
144
145       -r     Output  the raw metric values, do not convert counters to rates.
146              This option also causes pmdumptext to ignore  the  normalization
147              values for each metric.
148
149       -R     Repeat  the header every lines of output.  This option is useful
150              in interactive mode when using a graphical window to  avoid  the
151              header  scrolling beyond the window's buffer, and to realign the
152              header if the window is resized.
153
154       -s     pmdumptext will terminate after this many samples.
155
156       -t     The interval argument follows the  syntax  described  in  PCPIn‐
157              tro(1), and in the simplest form may be an unsigned integer (the
158              implied units in this case are seconds).  The  default  interval
159              is 1.0 seconds.
160
161       -u     Output  the  units  of  the metrics before the first values, but
162              after the metric names if -m is also specified.
163
164       -U     Change the output when values are unavailable  to  string.   The
165              default string is ``?''.
166
167       -w     Set  the  column width of the output.  Strings will be truncated
168              to this width, and maybe postfixed by ``...'' if  the  width  is
169              greater than 5.
170
171       -X     Output  the  column  number  and complete metric names, one-per-
172              line, both before dumping the first set of values and again each
173              time the header is repeated.
174
175       -z     Use  the  local  timezone  of the host that is the source of the
176              performance metrics, as identified by either the -h or the first
177              -a  options.   The  default  is to use the timezone of the local
178              host.
179
180       -Z     Use timezone when displaying the date and time.  Timezone is  in
181              the  format of the environment variable TZ as described in envi‐
182              ron(7).
183

MULTIPLE SOURCES

185       pmdumptext supports the dumping of metrics from multiple hosts  or  ar‐
186       chives.   The  metrics listed on the command line or in the config file
187       may have no specific source or come from different sources.
188
189       However, restrictions apply when archives are specified on the  command
190       line (-a) and/or in the configuration file.  Firstly, there may be only
191       one archive for any one host.  Secondly, the hosts of any metrics  with
192       host  sources  must correspond to the host of an archive, either on the
193       command line or previously as the source of another metric.
194
195       The options -a and -h may not be used together.
196

UNIT CONVERSION

198       All metrics that have the semantics of counters are automatically  con‐
199       verted  to  rates  over the sample time interval.  In interactive mode,
200       pmdumptext will also change the units of some metrics so that they  are
201       easier to comprehend:
202
203       o      All  metrics with space units (bytes to terabytes) are scaled to
204              bytes.  Note that 1024 bytes with be represented as  1.02K,  not
205              1.00K.
206
207       o      Metrics that are counters with time units (nanoseconds to hours)
208              represent time utilization over the sample interval.   The  unit
209              strings  of  such  metrics is changed to ``Time Utilization'' or
210              abbreviated to ``util'' and the values  are  normalized  to  the
211              range zero to one.
212

EXAMPLES

214       o To examine the load on two hosts foo and bar, simultaneously:
215
216     $ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
217                  Source        foo     bar
218     Wed Jul 30 11:37:53      0.309   0.409
219     Wed Jul 30 11:37:54      0.309   0.409
220     Wed Jul 30 11:37:55      0.309   0.409
221
222       o  To output the memory utilization on a remote host called bong with a
223       simpler timestamp:
224
225     $ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
226       Metric        kernel  fs_ctl  _dirty  _clean    free    user
227        Units             b       b       b       b       b       b
228     09:32:28         8.98M   0.97M   0.00    3.90M   7.13M  46.13M
229     09:32:29         8.99M   0.98M   0.00    5.71M   5.39M  46.03M
230     09:32:30         8.99M   1.07M   0.00    5.81M   4.55M  46.69M
231     09:32:31         9.03M   1.16M   0.00    6.45M   3.48M  47.00M
232     09:32:32         9.09M   1.18M  20.48K   6.23M   3.29M  47.30M
233
234       o To dump all metrics collected in an archive at a 30  second  interval
235       to a file for processing by another tool:
236
237     $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
238

FILES

240       $PCP_VAR_DIR/pmns/*
241                 default PMNS specification files
242

PCP ENVIRONMENT

244       Environment variables with the prefix PCP_ are used to parameterize the
245       file and directory names used by PCP.  On each installation,  the  file
246       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
247       $PCP_CONF variable may be used to specify an alternative  configuration
248       file, as described in pcp.conf(5).
249

SEE ALSO

251       pmchart(1),  pmtime(1),  PCPIntro(1),  pmcd(1),  pmlogger(1),  pmlogex‐
252       tract(1), pmrep(1), pmval(1), PMAPI(3), strftime(3) and environ(7).
253
254
255
256Performance Co-Pilot                  SGI                        PMDUMPTEXT(1)
Impressum