pmprobe(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMPROBE(1)               General Commands Manual              PMPROBE(1)

NAME         top

       pmprobe - lightweight probe for performance metrics

SYNOPSIS         top

       pmprobe [-dfFiILvVz?]  [-a archive] [-b batchsize]
       [--container=name] [--derived=file] [-h hostname] [-K spec] [-n
       pmnsfile] [-O time] [-Z timezone] [metricname ...]

DESCRIPTION         top

       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.

OPTIONS         top

       The available command line options are:

       -a archive, --archive=archive
            Performance metric values are retrieved from the set of
            Performance Co-Pilot (PCP) archive 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.

       --container=container
            Specify an individual container to be queried.

       -d, --version
            Display version number and exit.

       --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.

       -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.

       -F, --faster
            Assume given metric names are PMNS leaf nodes.

       -h host, --host=host
            Connect to pmcd(1) on host, rather than on the default
            localhost.

       -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.

       -I, --external
            Report the external identifiers for each instance.  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.

       -L, --local-PMDA
            Use a local context to collect metrics from DSO PMDAs on the
            local host without PMCD.  See also -K.

       -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.

       -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.

       -z, --hostzone
            Change the reporting timezone to the local timezone at the
            host that is the source of the performance metrics, as
            identified via either the -h or -a options.

       -Z timezone, --timezone=timezone
            By default, pmprobe reports the time of day according to the
            local timezone on the system where pmprobe is run.  The -Z
            option changes the timezone to timezone in the format of the
            environment variable TZ as described in environ(7).

       -?, --help
            Display usage message and exit.

EXAMPLES         top

       $ 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

FILES         top

       $PCP_VAR_DIR/pmns/*
            default PMNS specification files

PCP ENVIRONMENT         top

       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).

SEE ALSO         top

       PCPIntro(1), pmcd(1), pminfo(1), pmlogdump(1), PMAPI(3),
       pmErrStr(3), pmGetOptions(3), pmSpecLocalPMDA(3), pcp.conf(5),
       pcp.env(5) and PMNS(5).

COLOPHON         top

       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 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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: pcp-dstat(1)pminfo(1)pmrep(1)pmtrace(1)pmdatrace(3)pcp-dstat(5)