# pmval

## NAME



           **pmval** , **pmevent** - arbitrary performance metrics value dumper
    


## SYNOPSIS



           **pmval**[**-dgLrvVXz?**]  [**-a** _archive_] [**-A** _align_] [**--container** =_name_] [**-D**
           _debug_] [**--derived** =_file_] [**-f** _N_] [**-h** _host_] [**-i** _instances_] [**-K** _spec_]
           [**-n** _pmnsfile_] [**-O** _offset_] [**-p** _port_] [**-s** _samples_] [**-S** _starttime_]
           [**-t** _interval_] [**-T** _endtime_] [**-U** _archive_] [**-w** _width_] [**-x** _pattern_]
           [**-Z** _timezone_] _metricname_
    
           **pmevent**...
    


## 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 a set of
           archives 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 a set of archives, **pmval** may relinquish its own
           timing control, and operate under the control of a 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 client 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 output from **pmval** is directed to standard output.  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.
    
           **pmevent** is an alias for **pmval**.
    


## 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.  See also **-U**.
    
           **-A** _align_ , **--align** =_align_
                Force the initial sample to be aligned on the boundary of a
                natural time unit _align_.  Refer to PCPIntro(1) for a complete
                description of the syntax for _align_.
    
           **--container** =_container_
                Specify an individual _container_ to be queried.
    
           **-d** , **--delay**
                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.
    
           **--derived** =_file_
                Load derived metric definitions from _file_.
    
           **-f** _precision_ , **--precision** =_precision_
                Numbers are reported in ``fixed point'' notation, rather than
                the default scientific notation, using _precision_ digits for
                precision.  Each number will be up to the column width
                determined by the default heuristics, else the **-w** option if
                specified, and include _precision_ 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 _precision_ omits the
                decimal point and any fractional digits.
    
           **-g** , **--guimode**
                Start **pmval** as the sole client of a new pmtime(1) server
                process for replay of archived performance data using the
                pmtime(1) graphical user interface.
    
           **-h** _host_ , **--host** =_host_
                Fetch performance metrics from pmcd(1) on _host_ , rather than
                from the default localhost.
    
           **-i** _instances_ , **--instances** =_instances_
                Specify a list of one or more names of _instances_ 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** _spec_ , **--spec-local** =_spec_
                When fetching metrics from a local context (see **-L**), 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.
    
           **-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_
                Load an alternative Performance Metrics Name Space (PMNS(5))
                from the file _pmnsfile_.
    
           **-O** _origin_ , **--origin** =_origin_
                When reporting archived metrics, start reporting at _origin_
                within the time window (see **-S** and **-T**).  Refer to PCPIntro(1)
                for a complete description of the syntax for _origin_.
    
           **-p** _port_ , **--guiport** =_port_
                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** , **--raw**
                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** _samples_ , **--samples** =_samples_
                The _samples_ argument 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 set of PCP archives (in
                archive mode).
    
           **-S** _starttime_ , **--start** =_starttime_
                When reporting archived metrics, the report will be
                restricted to those records logged at or after _starttime_.
                Refer to PCPIntro(1) for a complete description of the syntax
                for _starttime_.
    
           **-t** _interval_ , **--interval** =_interval_
                Set the reporting _interval_ 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).
    
           **-T** _endtime_ , **--finish** =_endtime_
                When reporting archived metrics, the report will be
                restricted to those records logged before or at _endtime_.
                Refer to PCPIntro(1) for a complete description of the syntax
                for _endtime_.
    
           **-U** _archive_ , **--nointerp** =_archive_
                Performance metric values are retrieved from the Performance
                Co-Pilot (PCP) _archive_.  The argument 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.  However, 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.  See also **-a**.
    
                At most one of the options **-a** and **-U** may be specified.
    
           **-v** , **--verbose**
                Enable verbose mode.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-w** _width_ , **--width** =_width_
                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.
    
           **-x** _pattern_ , **--filter** =_pattern_
                The given _pattern_ is sent to the performance metric domain
                agent for the requested _metricname_ before any values are
                requested.  This serves two purposes.  Firstly, it provides a
                mechanism for server-side event filtering that is
                customisable for individual event streams.  In addition, some
                performance metrics domain agents also use the PMCD store
                mechanism to provide a basic security model (e.g. for
                sensitive log files, only a client host with pmStore(3)
                access would be able to access the event stream).
    
                As _pattern_ may be processed by regcomp(3) it should be a non-
                empty string.  Use . (dot) for a “match all” _pattern_.
    
           **-X** , **--timestamp**
                When replaying from an archive, this option requests that the
                timestamp be reported with additional date information and
                increased precision (microseconds with a single **-X** ,
                nanoseconds with an additional **-X**), for example
                **Sat May 22 20:32:20.971633 2021** instead of the default
                format, for example **20:32:20.971**.
    
           **-z** , **--hostzone**
                Use the local timezone of the host that is the source of the
                performance metrics, as identified by either the **-h** or the **-a**
                or the **-U** options.  The default is to use the timezone of the
                local host.
    
           **-Z** _timezone_ , **--timezone** =_timezone_
                Use _timezone_ for the date and time.  _Timezone_ is in the
                format of the environment variable **TZ** as described in
                environ(7).
    
           **-?** , **--help**
                Display usage message and exit.
    


## 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               │
                         └───────────┴──────────────────────┘
    


## 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 **pmval** are as follows:
           ┌────────┬───────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────┤
           │ **appl0** │ initial timeline positioning when **-a** used │
           └────────┴───────────────────────────────────────────┘
    


* * *