Provided by: pcp-gui_3.10.8build1_amd64 
NAME
pmdumptext - dump performance metrics to an ASCII table
SYNOPSIS
pmdumptext [-CFgGHilmMNoruXz] [-A align] [-a archive[,archive,...]] [-c config] [-d
delimiter] [-f format] [-h host] [-n pmnsfile] [-O offset] [-p port] [-P precision] [-R
lines] [-s sample] [-S starttime] [-t interval] [-T endtime] [-U string] [-w width] [-Z
timezone] [metric ...]
DESCRIPTION
pmdumptext outputs the values of performance metrics collected live or from a Performance
Co-Pilot (PCP) archive. By default, the metric values are displayed in tab separated
columns, prefixed by a timestamp.
Unless directed to another host by the -h option, or to one or more archives by the -a
option, pmdumptext will contact pmcd(1) on the local host to obtain the required
information.
pmdumptext may be run in interactive mode with the -i option which displays the values in
equal width columns. Without this option, no attempt is made to line up any values
allowing the output to be easily parsed by other applications.
The format of the output can be further controlled by changing the precision of the values
with -P, the width of the columns with -w, and the format of the values with the -G and -F
options for the shortest of scientific or fixed digits, and a fixed width format,
respectively.
The metrics to be dumped can be listed on the command line, in a config file, or piped to
pmdumptext on stdin. A metric consists of an optional source (host or archive), the
metric name, and an optional instance list immediately after the name. A colon is used to
separate a host name from the metric, and a forward slash (``/'') to separate an archive
name from the metric. Instances are enclosed in square brackets and a comma is used
between each instance if more than one is stated. For example, some legal metrics are:
kernel.all.cpu.idle
myhost:kernel.all.cpu.idle[cpu0,cpu3]
/path/to/myarchive/kernel.all.cpu.idle[cpu1]
The format of a metric is further described in PCPIntro(1). A normalization value may
optionally follow a metric name in a config file or on stdin. The metric value will be
scaled by this value. For example, if the file system ``/dev/root'' has a capacity of
1965437 bytes, then the percentage of the file system that is used could be dumped with
this config:
filesys.used[/dev/root] 19654.37
A normalization value may not be used with metrics specified as command line arguments.
A metric name is not required to be a leaf node in the Performance Metrics Name Space
(PMNS), except when one or more instances are specified. For example, to dump all file
system metrics, only filesys is required to dump filesys.capacity, filesys.used,
filesys.free etc.
COMMAND LINE OPTIONS
The command line options -A, -O, -S and -T control the alignment, offset, start and end
time when visualizing metrics from archives. These options are common to most Performance
Co-Pilot tools and are fully described in PCPIntro(1).
The other available options are:
-a Specify an archive from which metrics can be obtained for a particular host.
archive is the basename of an archive, previously created by pmlogger(1). Multiple
archives (separated by commas or in different -a options) from different hosts may
be given, but only one per host is permitted. Any metrics that are not associated
with a specific host or archive will use the first archive as their source.
-C Exit before dumping any values, but after parsing the metrics. Metrics, instances,
normals and units are listed if -m, -l, -N and/or -u are specified.
-c If no metrics are listed on the command line, a config file can be used to specify
the metrics to be dumped. Unlike the command line metrics, each metric may be
followed by a normalization value. Empty lines and lines that begin with ``#'' are
ignored.
-d Specify the delimiter that separates each column of output. The delimiter may only
be a single character.
-f Use the format string for formatting the timestamp with each set of values. The
syntax of this string is the same as that described in strftime(3). An empty
format string (eg. '') will remove the timestamps from the output.
-F Output the values in a fixed width format of 6 characters. Positive numbers are
represented as dd.ddu and negative numbers as [-]d.ddu. The postfix multiplier may
have the values K(10^3), M(10^6), G(10^9) and T(10^12). For example, 4567 would be
displayed as 4.57K, even if the units of the metric are bytes.
-G Output the values using the shortest of a scientific format or a decimal notation.
-g Run in graphical user interface (GUI) mode, with pmtime being used for VCR-alike
time control functionality.
-h Fetch performance metrics from pmcd(1) on host, rather than the default localhost.
-H Show all headers before dumping any metric values. This is equivalent to -lmNu.
-i Output the data in fixed width columns using fixed width values (see -F) so that it
is human-readable. This option may not be used with -P as fixed point values are
not fixed width. This option will also affect the output of -m and -u options as
the metric, instance and unit names will be truncated.
-l Show the source of the metrics. In interactive mode, the host of the metrics is
shown. In non-interactive mode, this option shows the source of the metrics with
the metric name even if -m is not specified.
-m Output the metric names before the metric values. The source and units of the
metrics may also be dumped with the -l and -u options respectively. If in
interactive mode, the metrics names may be truncated, and the instance names, where
relevant, are also truncated on the follow line.
-M Output the column number and complete metric names before dumping any values. If
the -l flag is also specified, the source of the metrics is also shown.
-n Load an alternative local PMNS from the file pmnsfile.
-o When a timestamp is being reported (ie. unless an empty format string is given with
the -f option), the timestamp is prefixed with the offset in seconds from the start
of the archive or the beginning of the execution of pmdumptext.
-N Output the normalization factors before the metric values.
-p Connect to pmtime(1) on the specified port.
-P Set the precision of the values. This option may not be used with -F as the
precision is constant. The default precision is 3.
-r Output the raw metric values, do not convert counters to rates. This option also
causes pmdumptext to ignore the normalization values for each metric.
-R Repeat the header every lines of output. This option is useful in interactive mode
when using a graphical window to avoid the header scrolling beyond the window's
buffer, and to realign the header if the window is resized.
-s pmdumptext will terminate after this many samples.
-t The interval argument follows the syntax described in PCPIntro(1), and in the
simplest form may be an unsigned integer (the implied units in this case are
seconds). The default interval is 1.0 seconds.
-u Output the units of the metrics before the first values, but after the metric names
if -m is also specified.
-U Change the output when values are unavailable to string. The default string is
``?''.
-w Set the column width of the output. Strings will be truncated to this width, and
maybe postfixed by ``...'' if the width is greater than 5.
-X Output the column number and complete metric names, one-per-line, both before
dumping the first set of values and again each time the header is repeated.
-z Use the local timezone of the host that is the source of the performance metrics,
as identified by either the -h or the first -a options. The default is to use the
timezone of the local host.
-Z Use timezone when displaying the date and time. Timezone is in the format of the
environment variable TZ as described in environ(7).
MULTIPLE SOURCES
pmdumptext supports the dumping of metrics from multiple hosts or archives. The metrics
listed on the command line or in the config file may have no specific source or come from
different sources.
However, restrictions apply when archives are specified on the command line (-a) and/or in
the configuration file. Firstly, there may be only one archive for any one host.
Secondly, the hosts of any metrics with host sources must correspond to the host of an
archive, either on the command line or previously as the source of another metric.
The options -a and -h may not be used together.
UNIT CONVERSION
All metrics that have the semantics of counters are automatically converted to rates over
the sample time interval. In interactive mode, pmdumptext will also change the units of
some metrics so that they are easier to comprehend:
o All metrics with space units (bytes to terabytes) are scaled to bytes. Note that
1024 bytes with be represented as 1.02K, not 1.00K.
o Metrics that are counters with time units (nanoseconds to hours) represent time
utilization over the sample interval. The unit strings of such metrics is changed
to ``Time Utilization'' or abbreviated to ``util'' and the values are normalized to
the range zero to one.
EXAMPLES
o To examine the load on two hosts foo and bar, simultaneously:
$ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
Source foo bar
Wed Jul 30 11:37:53 0.309 0.409
Wed Jul 30 11:37:54 0.309 0.409
Wed Jul 30 11:37:55 0.309 0.409
o To output the memory utilization on a remote host called bong with a simpler timestamp:
$ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
Metric kernel fs_ctl _dirty _clean free user
Units b b b b b b
09:32:28 8.98M 0.97M 0.00 3.90M 7.13M 46.13M
09:32:29 8.99M 0.98M 0.00 5.71M 5.39M 46.03M
09:32:30 8.99M 1.07M 0.00 5.81M 4.55M 46.69M
09:32:31 9.03M 1.16M 0.00 6.45M 3.48M 47.00M
09:32:32 9.09M 1.18M 20.48K 6.23M 3.29M 47.30M
o To dump all metrics collected in an archive at a 30 second interval to a file for
processing by another tool:
$ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile
FILES
$PCP_VAR_DIR/pmns/*
default PMNS specification files
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory
names used by PCP. On each installation, the file /etc/pcp.conf contains the local values
for these variables. The $PCP_CONF variable may be used to specify an alternative
configuration file, as described in pcp.conf(5).
SEE ALSO
pmchart(1), pmtime(1), PCPIntro(1), pmcd(1), pmlogger(1), pmlogextract(1), pmval(1),
PMAPI(3), strftime(3) and environ(7).