NAME¶
pmval - performance metrics value dumper
SYNOPSIS¶
pmval [
-dgrz] [
-A align] [
-a
archive] [
-f N] [
-h host] [
-i
instances] [
-K spec] [
-n pmnsfile] [
-O offset] [
-p port] [
-S
starttime] [
-s samples] [
-T endtime] [
-t interval] [
-U archive] [
-w
width] [
-Z timezone]
metricname
DESCRIPTION¶
pmval prints current or archived values for the nominated performance
metric. The metric of interest is named in the
metricname argument,
subject to instance qualification with the
-i flag as described below.
Unless directed to another host by the
-h option, or to an archive by the
-a or
-U options,
pmval will contact the Performance
Metrics Collector Daemon (PMCD) on the local host to obtain the required
information.
The
metricname argument may also be given in the metric specification
syntax, as described in
PCPIntro(1), where the source, metric and
instance may all be included in the
metricname, e.g.
thathost:kernel.all.load["1 minute"]. When this format is used, none
of the
-h or
-a or
-U options may be specified.
When using the metric specification syntax, the ``hostname''
@ is treated
specially and causes
pmval to use a local context to collect metrics
from PMDAs on the local host without PMCD. Only some metrics are available in
this mode.
When processing an archive,
pmval may relinquish its own timing control,
and operate as a ``slave'' of a
pmtime(1) process that uses a GUI
dialog to provide timing control. In this case, either the
-g option
should be used to start
pmval as the sole slave of a new
pmtime(1) instance, or
-p should be used to attach
pmval
to an existing
pmtime(1) instance via the IPC channel identified by the
port argument.
The
-S,
-T,
-O and
-A options may be used to define
a time window to restrict the samples retrieved, set an initial origin within
the time window, or specify a ``natural'' alignment of the sample times; refer
to
PCPIntro(1) for a complete description of these options.
The other options which control the source, timing and layout of the information
reported by
pmval are as follows:
- -a
- Performance metric values are retrieved from the Performance Co-Pilot
(PCP) archive log file identified by the base name archive.
- -d
- When replaying from an archive, this option requests that the prevailing
real-time delay be applied between samples (see -t) to effect a
pause, rather than the default behaviour of replaying at full speed.
- -f
- Numbers are reported in ``fixed point'' notation, rather than the default
scientific notation. Each number will be up to the column width determined
by the default heuristics, else the -w option if specified, and
include N digits after the decimal point. So, the options -f 3
-w 8 would produce numbers of the form 9999.999. A value of zero for
N omits the decimal point and any fractional digits.
- -g
- Start pmval as the slave of a new pmtime(1) process for
replay of archived performance data using the pmtime(1) graphical
user interface.
- -h
- Current performance metric values are retrieved from the nominated
host machine.
- -i
- instances is a list of one or more instance names for the nominated
performance metric - just these instances will be retrieved and reported
(the default is to report all instances). The list must be a single
argument, with elements of the list separated by commas and/or white
space.
The instance name may be quoted with single (') or double (") quotes for
those cases where the instance name contains white space or commas.
Multiple
-i options are allowed as an alternative way of specifying more
than one instance of interest.
As an example, the following are all equivalent:
$ pmval -i "'1 minute','5 minute'" kernel.all.load
$ pmval -i '"1 minute","5 minute"' kernel.all.load
$ pmval -i "'1 minute' '5 minute'" kernel.all.load
$ pmval -i "'1 minute'" -i "'5 minute'" kernel.all.load
$ pmval 'localhost:kernel.all.load["1 minute","5 minute"]'
- -K
- When fetching metrics from a local context, the -K option may be
used to control the DSO PMDAs that should be made accessible. The
spec argument conforms to the syntax described in
__pmSpecLocalPMDA(3). More than one -K option may be
used.
- -n
- Normally pmval operates on the default Performance Metrics Name
Space (PMNS), however if the -n option is specified an alternative
namespace is loaded from the file pmnsfile.
- -p
- Attach pmval to an existing pmtime(1) time control process
instance via the IPC channel identified by the port argument. This
option is normally only used by other tools, e.g. pmchart(1), when
they launch pmval with synchronized time control.
- -r
- Print raw values for cumulative counter metrics. Normally cumulative
counter metrics are converted to rates. For example, disk transfers are
reported as number of disk transfers per second during the preceding
sample interval, rather than the raw value of number of disk transfers
since the machine was booted. If you specify this option, the raw metric
values are printed.
- -s
- The argument samples defines the number of samples to be retrieved
and reported. If samples is 0 or -s is not specified,
pmval will sample and report continuously (in real time mode) or
until the end of the PCP archive (in archive mode).
- -t
- The default update interval may be set to something other than the
default 1 second. 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).
- -U
- Performance metric values are retrieved from the Performance Co-Pilot
(PCP) archive log file identified by the base name archive,
although unlike -a every recorded value in the archive for the
selected metric and instances is reported (so no interpolation mode, and
the sample interval (-t option) is ignored.
At most one of the options
-a and
-U may be specified.
- -w
- Set the width of each column of output to be width columns. If not
specified columns are wide enough to accommodate the largest value of the
type being printed.
- -Z
- By default, pmval reports the time of day according to the local
timezone on the system where pmval is run. The -Z option
changes the timezone to timezone in the format of the environment
variable TZ as described in environ(5).
- -z
- Change the reporting timezone to the local timezone at the host that is
the source of the performance metrics, as identified via either the
metricname or the -h or -a or -U options.
The following symbols may occasionally appear, in place of a metric value, in
pmval output: A question mark symbol (?) indicates that a value is no
longer available for that metric instance. An exclamation mark (!) indicates
that a 64-bit counter wrapped during the sample.
The output from
pmval is directed to standard output.
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¶
PCPIntro(1),
pmcd(1),
pmchart(1),
pmdumplog(1),
pminfo(1),
pmlogger(1),
pmtime(1),
PMAPI(3),
__pmSpecLocalPMDA(3),
pcp.conf(5) and
pcp.env(5).
DIAGNOSTICS¶
All are generated on standard error and are intended to be self-explanatory.
CAVEATS¶
By default,
pmval attempts to display non-integer numeric values in a way
that does not distort the inherent precision (rarely more than 4 significant
digits), and tries to maintain a tabular format in the output. These goals are
sometimes in conflict.
In the absence of the
-f option (described above), the following table
describes the formats used for different ranges of numeric values for any
metric that is of type
PM_TYPE_FLOAT or
PM_TYPE_DOUBLE, or any
metric that has the semantics of a counter (for which
pmval reports the
rate converted value):
Format |
Value Range |
|
! |
No values available |
9.999E-99 |
< 0.1 |
0.0 |
0 |
9.9999 |
> 0 and <= 0.9999 |
9.999 |
> 0.9999 and < 9.999 |
99.99 |
> 9.999 and < 99.99 |
999.9 |
> 99.99 and < 999.9 |
9999. |
> 999.9 and < 9999 |
9.999E+99 |
> 9999 |