# pcp

## NAME



           **pcp** , **pcp-summary** - run a command or summarize an installation
    


## SYNOPSIS



           **pcp**[pcp options...]  _pcp-command_ [command options...]
           **pcp**[**-LPV?**]  [**-a** _archive_] [**-D** _debug_] [**-h** _host_] [**-O** _origin_] [**-n**
           _pmnsfile_]
    


## DESCRIPTION



           The **pcp** command is used in one of two modes.  By default, it
           summarizes the Performance Co-Pilot (PCP) installation on the
           local host.  This mode can also be used to summarize the
           installation from a remote _host_ , or a historical installation from
           a set of PCP _archives_.  This mode indirectly invokes the **pcp-**
           **summary** _command_ (in the absence of any other requested command).
    
           Alternatively, a _command_ can be passed to **pcp** to run, again
           possibly in the context of a remote _host_ or set of historical
           _archives_.
    


## COMMAND MODE



           When **pcp** is invoked with a command to run, it will search for the
           named _command_ in **$PCP_BINADM_DIR** and also **$HOME/.pcp/bin**(these
           are usually scripts, and are installed with a "pcp-" prefix).
           This mode of operation allows system performance tools to be
           implemented using PMAPI(3) services, while still preserving all of
           their usual command line options.  These options are thus
           (indirectly) augmented with the standard PCP option set, as
           described in PCPIntro(1).
    
           This provides a convenient mechanism for obtaining retrospective
           or remote monitoring capabilities while preserving the behaviour
           of the system tools.
    
           For example, the pcp-free(1) utility can be invoked as follows,
           for recorded data from host _munch_ :
    
           $ pcp -a $PCP_LOG_DIR/pmlogger/_munch_ /20140317 -O 11:35:50am **free -m**
                        total       used       free     shared    buffers     cached
           Mem:         23960      14554       9406          0        176       2137
           -/+ buffers/cache:      12240      11720
           Swap         12047          0      12047
    
           A complete list of the available and installed tools is provided
           along with the pcp(1) usage message, but some examples include:
           pcp-free(1), pcp-uptime(1) and pcp-numastat(1).
    


## SUMMARY MODE



           The summary report includes: the OS version, a summary of the
           hardware inventory, the local timezone, the PCP software version,
           the state of the pmcd(1) process and associated Performance
           Metrics Domain Agents (PMDAs), as well as information about any
           PCP archivers (pmlogger(1)) and PCP inference engines (pmie(1))
           that are running.
    
           All of the displayed values are performance _metric_ values and
           further information for each can be obtained using the command:
    
              $ pminfo -dtT _metric_
    
           The complete set of _metric_ s required by **pcp** to produce its output
           is contained in **$PCP_VAR_DIR/config/pmlogconf/tools/pcp-summary**.
    


## SUMMARY MODE OPTIONS



           With no arguments, **pcp** reports on the local host, however the
           following options are accepted:
    
           **-a** _archive_ , **--archive** =_archive_
                Report the PCP configuration as described in the set of PCP
                archives, _archive_ , 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.
    
           **-h** _host_ , **--host** =_host_
                Report the PCP configuration on _host_ rather than the local
                host.
    
           **-L** , **--local-PMDA**
                Use a local context to collect metrics from DSO PMDAs on the
                local host without PMCD.
    
           **-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.
    
           **-P** , **--pmie**
                Display pmie(1) performance information - counts of rules
                evaluating to true, false, or indeterminate, as well as the
                expected rate of rule calculation, for each **pmie** process
                running on the default host.  Refer to the individual metric
                help text for full details on these values.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-?** , **--help**
                Display usage message and exit.
    


## DIAGNOSTICS



           **pcp** will terminate with an exit status of **1** if **pmcd** on the target
           host could not be reached or the set of archives could not be
           opened, or **2** for any other error.
    


## FILES



           _$HOME/.pcp/bin_
                Per-user location for _command_ scripts.
    
           _$PCP_BINADM_DIR_
                System location for installed _command_ scripts.
    
           _$PCP_VAR_DIR/config/pmlogconf/tools/pcp-summary_
                pmlogconf(1) configuration file for collecting all of the
                metrics required by **pcp**
    


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


* * *