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

OPTIONS

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

MULTIPLE SOURCES

210       pmdumptext  supports  the dumping of metrics from multiple hosts or set
211       of archives.  The metrics listed on the command line or in  the  config
212       file may have no specific source or come from different sources.
213
214       However,  restrictions apply when archives are specified on the command
215       line (-a) and/or in the configuration file.  Firstly, there may be only
216       one  set of archives for any one host.  Secondly, the hosts of any met‐
217       rics with host sources must correspond to the host  of  a  set  of  ar‐
218       chives,  either  on  the  command  line  or previously as the source of
219       another metric.
220
221       The options -a and -h may not be used together.
222

UNIT CONVERSION

224       All metrics that have the semantics of counters are automatically  con‐
225       verted  to  rates  over the sample time interval.  In interactive mode,
226       pmdumptext will also change the units of some metrics so that they  are
227       easier to comprehend:
228
229       o      All  metrics with space units (bytes to terabytes) are scaled to
230              bytes.  Note that 1024 bytes with be represented as  1.02K,  not
231              1.00K.
232
233       o      Metrics that are counters with time units (nanoseconds to hours)
234              represent time utilization over the sample interval.   The  unit
235              strings  of  such  metrics is changed to ``Time Utilization'' or
236              abbreviated to ``util'' and the values  are  normalized  to  the
237              range zero to one.
238

EXAMPLES

240       o To examine the load on two hosts foo and bar, simultaneously:
241
242     $ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
243                  Source        foo     bar
244     Wed Jul 30 11:37:53      0.309   0.409
245     Wed Jul 30 11:37:54      0.309   0.409
246     Wed Jul 30 11:37:55      0.309   0.409
247
248       o  To output the memory utilization on a remote host called bong with a
249       simpler timestamp:
250
251     $ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
252       Metric        kernel  fs_ctl  _dirty  _clean    free    user
253        Units             b       b       b       b       b       b
254     09:32:28         8.98M   0.97M   0.00    3.90M   7.13M  46.13M
255     09:32:29         8.99M   0.98M   0.00    5.71M   5.39M  46.03M
256     09:32:30         8.99M   1.07M   0.00    5.81M   4.55M  46.69M
257     09:32:31         9.03M   1.16M   0.00    6.45M   3.48M  47.00M
258     09:32:32         9.09M   1.18M  20.48K   6.23M   3.29M  47.30M
259
260       o To dump all metrics collected in an archive at a 30  second  interval
261       to a file for processing by another tool:
262
263     $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
264

FILES

266       $PCP_VAR_DIR/pmns/*
267                 default PMNS specification files
268

PCP ENVIRONMENT

270       Environment variables with the prefix PCP_ are used to parameterize the
271       file and directory names used by PCP.  On each installation,  the  file
272       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
273       $PCP_CONF variable may be used to specify an alternative  configuration
274       file, as described in pcp.conf(5).
275
276       For environment variables affecting PCP tools, see pmGetOptions(3).
277

SEE ALSO

279       PCPIntro(1),  pmcd(1),  pmchart(1),  pmlogger(1),  pmrep(1),  PMAPI(3),
280       strftime(3) and environ(7).
281
282
283
284Performance Co-Pilot                  SGI                        PMDUMPTEXT(1)
Impressum