NAME
pmdumptext - performance metrics dump to an ASCII table
SYNOPSIS
pmdumptext [-CFgHilmMNoruz] [-A align] [-a
archive[,archive,...]] [-c config] [-d delimiter] [-f
format] [-h host] [-n pmnsfile] [-O offset] [-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 col
lected live or from a Performance Co-Pilot (PCP(1))
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 PCPIn
tro(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
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 speci
fied 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 com
mas or in different -a options) from different
hosts may be given, but only one per host is per
mitted. 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 charac
ter.
-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
-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 post
fix 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 scien
tific format or a decimal notation.
-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 -E as fixed point
values are not fixed width. This option will also
affect the output of -m and -u options as the met
ric, 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 trun
cated, 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 pmns
file.
-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 sec
onds from the start of the archive or the beginning
of the execution of pmdumptext.
-N Output the normalization factors before the metric
values.
not be used with -F as the precision is constant.
The default precision is 3.
-r Output the raw metric values, do not convert coun
ters 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.
-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 vari
able TZ as described in environ(5).
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 com
mand line or previously as the source of another metric.
UNIT CONVERSION
All metrics that have the semantics of counters are auto
matically converted to rates over the sample time inter
val. In interactive mode, pmdumptext will also change the
units of some metrics so that they are easier to compre
hend:
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 (nanosec
onds 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, simultane
ously:
$ 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
bing with a simpler timestamp:
$ pmdumptext -imu -h bing -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 sec
ond 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
local values for these variables. The $PCP_CONF variable
may be used to specify an alternative configuration file,
as described in pcp.conf(4).
SEE ALSO
pcp(1), PCPIntro(1), pmcd(1), pmdumpmineset(1), pmlog
ger(1), pmlogmerge(1), pmval(1), PMAPI(3), strftime(3) and
environ(5).
Man(1) output converted with
man2html