1PMDUMPTEXT(1) General Commands Manual PMDUMPTEXT(1)
2
6 pmdumptext - dump performance metrics to an ASCII table
7
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
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 the Perfor‐
22 mance Metrics Collector Daemon (PMCD) on the local host to obtain the
23 required information.
24 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 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 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 kernel.all.cpu.idle
45 myhost:kernel.all.cpu.idle[cpu0,cpu3]
46 /path/to/myarchive/kernel.all.cpu.idle[cpu1]
47 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 filesys.used[/dev/root] 19654.37
56 A normalization value may not be used with metrics specified as command
58 line arguments.
59 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
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 The other available options are:
72 -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 -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 -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 -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 -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 -G, --scientific
111 Output the values using the shortest of a scientific format or a
112 decimal notation.
113 -h host, --host=host
115 Fetch performance metrics from pmcd(1) on host, rather than the
116 default localhost.
117 -H, --headers
119 Show all headers before dumping any metric values. This is equiv‐
120 alent to -lmNu.
121 -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 -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 -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 -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 -n pmnsfile, --namespace=pmnsfile
147 Load an alternative local PMNS from the file pmnsfile.
148 -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 -N Output the normalization factors before the metric values.
156 -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 -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 -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 -s samples, --samples=samples
173 pmdumptext will terminate after this many samples.
174 -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 -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 -U string, --unavailable=string
186 Change the output when values are unavailable to string. The
187 default string is ``?''.
188 -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 -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 -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 -?, --help
207 Display usage message and exit.
208
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 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 The options -a and -h may not be used together.
222
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 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 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
240 o To examine the load on two hosts foo and bar, simultaneously:
241 $ 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 o To output the memory utilization on a remote host called bong with a
249 simpler timestamp:
250 $ 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 o To dump all metrics collected in an archive at a 30 second interval
261 to a file for processing by another tool:
262 $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
264
266 $PCP_VAR_DIR/pmns/*
267 default PMNS specification files
268
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 For environment variables affecting PCP tools, see pmGetOptions(3).
277
279 PCPIntro(1), pmcd(1), pmchart(1), pmlogger(1), pmrep(1), PMAPI(3),
280 strftime(3) and environ(7).
281Performance Co-Pilot SGI PMDUMPTEXT(1)