1PMDUMPTEXT(1) General Commands Manual PMDUMPTEXT(1)
2
6 pmdumptext - dump performance metrics to an ASCII table
7
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
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 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 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 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 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 kernel.all.cpu.idle
44 myhost:kernel.all.cpu.idle[cpu0,cpu3]
45 /path/to/myarchive/kernel.all.cpu.idle[cpu1]
46 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 filesys.used[/dev/root] 19654.37
55 A normalization value may not be used with metrics specified as command
57 line arguments.
58 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
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 The other available options are:
71 -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 -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 -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 -d Specify the delimiter that separates each column of output. The
91 delimiter may only be a single character.
92 -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 -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 -G Output the values using the shortest of a scientific format or a
105 decimal notation.
106 -h Fetch performance metrics from pmcd(1) on host, rather than the
108 default localhost.
109 -H Show all headers before dumping any metric values. This is
111 equivalent to -lmNu.
112 -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 -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 -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 -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 -n Load an alternative local PMNS from the file pmnsfile.
135 -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 -N Output the normalization factors before the metric values.
142 -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 -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 -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 -s pmdumptext will terminate after this many samples.
157 -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 -u Output the units of the metrics before the first values, but
164 after the metric names if -m is also specified.
165 -U Change the output when values are unavailable to string. The
167 default string is ``?''.
168 -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 -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 -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 -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
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 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 The options -a and -h may not be used together.
199
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 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 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
217 o To examine the load on two hosts foo and bar, simultaneously:
218 $ 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 o To output the memory utilization on a remote host called bong with a
226 simpler timestamp:
227 $ 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 o To dump all metrics collected in an archive at a 30 second interval
238 to a file for processing by another tool:
239 $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
241
243 $PCP_VAR_DIR/pmns/*
244 default PMNS specification files
245
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
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).
256Performance Co-Pilot SGI PMDUMPTEXT(1)