# pmprobe

## NAME



           **pmprobe** - lightweight probe for performance metrics
    


## SYNOPSIS



           **pmprobe**[**-dfFiILvVz?**]  [**-a** _archive_] [**-b** _batchsize_]
           [**--container** =_name_] [**-D** _debug_] [**--derived** =_file_] [**-h** _hostname_] [**-K**
           _spec_] [**-n** _pmnsfile_] [**-O** _time_] [**-Z** _timezone_] [_metricname_ ...]
    


## DESCRIPTION



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



           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



           $ 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



           _$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).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmprobe** are as follows:
           ┌────────┬────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼────────────────────────────────┤
           │ **appl0** │ batch information when **-b** used │
           └────────┴────────────────────────────────┘
    


* * *