|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON |
PMPROBE(1) General Commands Manual PMPROBE(1)
pmprobe - lightweight probe for performance metrics
pmprobe [-fFIiLVvz?] [-a archive] [-b batchsize] [-h hostname] [-K
spec] [-n pmnsfile] [-O time] [-Z timezone] [--container=name]
[--derived=file] [metricname ...]
pmprobe determines the availability of performance metrics exported
through the facilities of the Performance Co-Pilot (PCP).
The metrics of interest are named in the metricname arguments. If
metricname is a non-leaf node in the Performance Metrics Name Space
(PMNS(5)), then pmprobe will recursively descend the PMNS and report
on all leaf nodes. If no metricname argument is given, the root of
the namespace is used.
This recursive expansion of the PMNS can be inhibited by the -F (go
faster) option, which reduces the number of roundtrips to pmcd(1)
when the metricname arguments are known to be leaf nodes ahead of
time.
The output format is spartan and intended for use in wrapper scripts
creating configuration files for other PCP tools. By default, there
is one line of output per metric, with the metric name followed by a
count of the number of available values. Error conditions are
encoded as a negative value count (as per the PMAPI(3) protocols, but
may be decoded using pmerr(1)) and followed by a textual description
of the error.
Unless directed to another host by the -h option, pmprobe will
contact the Performance Metrics Collector Daemon (PMCD) on the local
host.
The -a option causes pmprobe to use the specified set of archives
rather than connecting to a PMCD.
The -L option causes pmprobe to use a local context to collect
metrics from PMDAs on the local host without PMCD. Only some metrics
are available in this mode.
The -a, -h and -L options are mutually exclusive.
The available command line options are:
-a archive, --archive=archive
Performance metric values are retrieved from the set of
Performance Co-Pilot (PCP) archive log files identified by the
archive argument, which is a comma-separated list of names, each
of which may be the base name of an archive or the name of a
directory containing one or more archives.
-b, --batch
This option may be used to define the maximum number of metrics
to be fetched in a single request for the -v option and any
pmLookupName(3) request that pmprobe calls with a list of leaf
metric names. The default value for batchsize is 128. This
option is useful to avoid limitations on PDU request sizes and
also to stagger fetches, which may otherwise timeout if pmcd(1)
or a PMDA is slow to respond, particularly if a large number of
metrics are probed.
-n pmnsfile, --namespace=pmnsfile
Normally pmprobe operates on the distributed Performance Metrics
Name Space (PMNS), however, if the -n option is specified an
alternative local PMNS file is loaded from the file pmnsfile.
-f, --force
When used with -i or -I the set of instances reported will be
all of those known at the source of the performance data. By
default the set of reported instances are those for which values
are currently available, which may be smaller than the set
reported with -f.
-I, --external
Report the external identifiers for each instance. The literal
string PM_IN_NULL is reported for singular metrics.
-i, --internal
Report the internal identifiers for each instance. The values
are in decimal and prefixed by ``?''. As a special case, the
literal string PM_IN_NULL is reported for singular metrics.
-K spec, --spec-local=spec
When using the -L/ option to fetch metrics from a local context,
this option controls 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.
-O time, --origin=time
When used in conjunction with an archive source of metrics and
the options -f/, the time argument defines a time origin at
which the metrics should be fetched from the set of archives.
Refer to PCPIntro(1) for a complete description of this option,
and the syntax for the time argument.
-v, --values
Report the value for each instance, as per the formatting rules
of pmPrintValue(3). When fetching from a set of archives, only
those instances present in the first archive record for a metric
will be displayed; see also the -O option. The -v option is
mutually exclusive with either the -I or -i options.
-V, --verbose
This option provides a cryptic summary of the number of messages
sent and received across the PMAPI interface.
-?, --help
Display usage message and exit.
--container=container
Specify an individual container to be queried.
--derived=dmfile
The dmfile argument specifies a file that contains derived
metric definitions in the format described for
pmLoadDerivedConfig(3). This option provides a way to load
derived metric definitions that is an alternative to the more
generic use of the PCP_DERIVED_CONFIG environment variable as
described in PCPIntro(1). Using the --derived option and the
PCP_DERIVED_CONFIG environment variable to specify the same
configuration is a bad idea, so choose one or the other method.
$ pmprobe disk.dev
disk.dev.read 2
disk.dev.write 2
disk.dev.total 2
disk.dev.blkread 2
disk.dev.blkwrite 2
disk.dev.blktotal 2
disk.dev.active 2
disk.dev.response 2
$ pmprobe -I disk.dev.read disk.dev.write disk.all.total
disk.dev.read 2 "sda" "sdb"
disk.dev.write 2 "sda" "sdb"
disk.all.total 1 PM_IN_NULL
$ pmprobe -v pmcd.numagents pmcd.version pmcd.control.timeout
pmcd.numagents 1 9
pmcd.version 1 "5.0.0"
pmcd.control.timeout 1 5
$ pmprobe -v disk.dev.total disk.all.total
disk.dev.total -1012 Unknown metric name
disk.all.total 1 4992466
$PCP_VAR_DIR/pmns/*
default PMNS specification files
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).
For environment variables affecting PCP tools, see pmGetOptions(3).
PCPIntro(1), pmcd(1), pmdumplog(1), pminfo(1), PMAPI(3), pmErrStr(3),
pmGetOptions(3), pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and
PMNS(5).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2020-08-13. (At that time, the date of the most recent commit that
was found in the repository was 2020-08-11.) If you discover any
rendering problems in this HTML version of the page, or you believe
there is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Performance Co-Pilot PCP PMPROBE(1)
Pages that refer to this page: pcp2csv(1) , pcp-dstat(1) , pminfo(1) , pmrep(1) , pmtrace(1) , pmdatrace(3) , pmtraceabort(3) , pmtracebegin(3) , pmtracecounter(3) , pmtraceend(3) , pmtraceerrstr(3) , pmtraceobs(3) , pmtracepoint(3) , pmtracestate(3) , pcp-dstat(5)