# pmclient

## NAME



           **pmclient** , **pmclient_fg** - a simple performance metrics client
    


## SYNOPSIS



           **pmclient**[**-PVz?**]  [**-a** _archive_] [**-A** _align_] [**-D** _debug_] [**-h** _host_] [**-n**
           _pmnsfile_] [**-O** _origin_] [**-s** _samples_] [**-S** _starttime_] [**-t** _interval_]
           [**-T** _endtime_] [**-Z** _timezone_]
    
           **pmclient_fg**...
    


## DESCRIPTION



           **pmclient** and **pmclient_fg** are simple clients that use the
           Performance Metrics Application Programming Interface (PMAPI) to
           report some high-level system performance metrics.
    
           The real value of these tools is as sample clients using the
           PMAPI(3), interfaces and to this end the source code is included
           with the Performance Co-Pilot (PCP) package (see PCPIntro(1)), and
           is typically installed in _/usr/share/pcp/demos/pmclient_.
    
           The **pmclient_fg** program differs to **pmclient** in that it uses the
           fetchgroup API extension to the PMAPI, see pmFetchGroup(3).
    
           Normally **pmclient** operates on the distributed Performance Metrics
           Name Space (PMNS), however if the **-n** option is specified an
           alternative local PMNS is loaded from the file _pmnsfile_.
    
           Unless directed to another host by the **-h** option, or to an archive
           by the **-a** option, **pmclient** will contact the Performance Metrics
           Collector Daemon (PMCD) on the local host to obtain the required
           information.  The argument to **-a** 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.  The **-a** and
           **-h** options are mutually exclusive.
    
           By default, **pmclient** reports the time of day according to the
           local timezone on the system where **pmclient** is run.  The **-Z** option
           changes the timezone to _timezone_ in the format of the environment
           variable **TZ** as described in environ(7).  The **-z** option changes the
           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.
    
           The output from **pmclient** is directed to standard output, and lists
    
           +  Aggregate CPU utilization, in the range 0 to 1.
    
           +  If the system has more than 1 CPU, the ordinal number of the
              busiest CPU, in the range 0 to ...
    
           +  If the system has more than 1 CPU, the CPU utilization for the
              busiest CPU.
    
           +  Real free memory in Mbytes.
    
           +  Aggregate physical disk I/O operations per second (IOPS).
    
           +  Load average over the last 1 minute and over the last 15
              minutes.
    


## 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.
    
           **-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_.
    
           **-h** _host_ , **--host** =_host_
                Fetch performance metrics from pmcd(1) on _host_ , rather than
                from the default localhost.
    
           **-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** , **--pause**
                The default behavior for replaying a set of archives, is to
                replay at full speed.  The **-P** option may be used in
                conjunction with a set of archives, to request that the
                prevailing real-time delay be applied between samples (see
                **-t**) to effect a pause.
    
           **-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, **pmclient** 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_
                The **-S** option may be used in conjunction with a set of
                archives to request that display start at the _starttime_ from
                the start of the archive(s).  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 5 seconds.  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_.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-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**
                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.
    


## FILES



           _$PCP_DEMOS_DIR/pmclient_
                source code, documentation, configuration files and Makefile
                when the PCP development package is installed
    


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


* * *