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
option, or to one or more archives by the
on the local host to obtain the required information.
may be run in interactive mode with the
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
the width of the columns with
and the format of the values with the
options for the shortest of scientific or fixed digits, and a fixed
width format, respectively.
to be dumped can be listed on the command line, in a
file, or piped to
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:
The format of a metric is further described in
A normalization value may optionally follow a metric name in a
file or on
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
A normalization value may not be used with
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
is required to dump
COMMAND LINE OPTIONS
The command line options
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
The other available options are:
from which metrics can be obtained for a particular host.
is the basename of an archive, previously created by
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.
Exit before dumping any values, but after parsing the metrics. Metrics,
instances, normals and units are listed if
are listed on the command line, a
file can be used to specify the
to be dumped.
Unlike the command line
each metric may be followed by a normalization value. Empty lines and
lines that begin with ``#'' are ignored.
that separates each column of output. The
may only be a single character.
string for formatting the timestamp with each set of values. The syntax of
this string is the same as that described in
string (eg. '') will remove the timestamps from the output.
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
For example, 4567 would be displayed as 4.57K, even if the units of the metric
Output the values using the shortest of a scientific format or a decimal
Run in graphical user interface (GUI) mode, with
being used for VCR-alike time control functionality.
Fetch performance metrics from
rather than the default localhost.
Show all headers before dumping any metric values. This is equivalent to
Output the data in fixed width columns using fixed width values (see
so that it is human-readable. This option may not be used with
as fixed point values are not fixed width. This option will also affect the
options as the metric, instance and unit names will be truncated.
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
is not specified.
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
Output the column number and complete metric names before dumping any values.
flag is also specified, the source of the metrics is also shown.
Load an alternative local PMNS from the file
When a timestamp is being reported (ie. unless an empty format string is
given with the
option), the timestamp is prefixed with the offset in seconds from
the start of the archive or the beginning of the execution of
Output the normalization factors before the metric values.
of the values. This option may not be used with
as the precision is constant. The default precision is 3.
Output the raw metric values, do not convert counters to rates. This option
to ignore the normalization values for each metric.
Repeat the header every
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.
will terminate after this many samples.
argument follows the syntax described in
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.
Output the units of the metrics before the first values, but after the metric
names if -m is also specified.
Change the output when values are unavailable to
The default string is ``?''.
Set the column width of the output. Strings will be truncated to this width,
and maybe postfixed by ``...'' if the
is greater than 5.
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.
Use the local timezone of the host that is the source of the
performance metrics, as identified by either the
or the first
The default is to use the timezone of the local host.
when displaying the date and time.
is in the format of the environment variable
as described in
supports the dumping of metrics from multiple hosts or archives. The metrics
listed on the command line or in the
file may have no specific source or come from different sources.
However, restrictions apply when archives
are specified on the command line
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.
may not be used together.
All metrics that have the semantics of counters are automatically converted to
rates over the sample time interval. In interactive mode,
will also change the units of some metrics so that they are easier to
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.
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.
o To examine the load on two hosts foo and bar, simultaneously:
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
default PMNS specification files
Environment variables with the prefix
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
contains the local values for these variables.
variable may be used to specify an alternative
as described in