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

OPTIONS

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

MULTIPLE SOURCES

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

UNIT CONVERSION

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

EXAMPLES

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

FILES

243       $PCP_VAR_DIR/pmns/*
244                 default PMNS specification files
245

PCP ENVIRONMENT

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

SEE ALSO

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