1PMDUMPTEXT(1) General Commands Manual PMDUMPTEXT(1)
2
6 pmdumptext - dump performance metrics to an ASCII table
7
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
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, 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 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 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 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 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 kernel.all.cpu.idle
51 myhost:kernel.all.cpu.idle[cpu0,cpu3]
52 /path/to/myarchive/kernel.all.cpu.idle[cpu1]
53 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 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 filesys.used[/dev/root] 19654.37
73 A normalization value may not be used with metrics specified as command
75 line arguments.
76 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
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 The other available options are:
90 -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 -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 -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 -d delimiter, --delimiter=delimiter
114 Specify the delimiter that separates each column of output. The
115 delimiter may only be a single character.
116 -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 -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 -G, --scientific
131 Output the values using the shortest of a scientific format or a
132 decimal notation.
133 -h host, --host=host
135 Fetch performance metrics from pmcd(1) on host, rather than the
136 default localhost.
137 -H, --headers
139 Show all headers before dumping any metric values. This is equiv‐
140 alent to -lmNu.
141 -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 -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 -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 -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 -n pmnsfile, --namespace=pmnsfile
167 Load an alternative local PMNS from the file pmnsfile.
168 -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 -N Output the normalization factors before the metric values.
176 -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 -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 -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 -s samples, --samples=samples
194 pmdumptext will terminate after this many samples.
195 -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 -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 -U string, --unavailable=string
207 Change the output when values are unavailable to string. The de‐
208 fault string is ``?''.
209 -V, --version
211 Display version number and exit.
212 -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 -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 -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 -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 -?, --help
233 Display usage message and exit.
234
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 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 The options -a and -h may not be used together.
248
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 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 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
266 o To examine the load on two hosts foo and bar, simultaneously:
267 $ 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 o To output the memory utilization on a remote host called bong with a
275 simpler timestamp:
276 $ 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 o To dump all metrics collected in an archive at a 30 second interval
287 to a file for processing by another tool:
288 $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
290
292 $PCP_VAR_DIR/pmns/*
293 default PMNS specification files
294
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 For environment variables affecting PCP tools, see pmGetOptions(3).
303
305 PCPIntro(1), pmcd(1), pmchart(1), pmlogger(1), pmrep(1), PMAPI(3),
306 strftime(3) and environ(7).
307Performance Co-Pilot SGI PMDUMPTEXT(1)