NAME

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

SYNOPSIS

       pcp [pcp options...]  pcp-command [command options...]
       pcp [-P] [-a archive] [-h host] [-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 PCP archive.
       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 historical archive.

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  archive
       loggers (pmlogger(1)) and PCP inference engines (pmie(1)) that are running.

       With  no  arguments,  pcp  reports  on  the  local host, however the following options are
       accepted:

       -a archive
              Report the PCP configuration as described in the PCP archive log archive.

       -h host
              Report the PCP configuration on host rather than the local host.

       -n pmnsfile
              Load an  alternative  Performance  Metrics  Name  Space  (pmns(5))  from  the  file
              pmnsfile.

       -P     Display  pmie  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.

       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  metrics  required  by  pcp  to  produce its output is contained in
       $PCP_VAR_DIR/config/pmlogconf/tools/pcp-summary.

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

SEE ALSO

       PCPIntro(1), pcp-free(1), pcp-numastat(1),  pcp-python(1),  pcp-uptime(1),  pcp-verify(1),
       pmcd(1), pmie(1), pmlogconf(1), pmlogger(1), pcp.conf(5) and pcp.env(5).

DIAGNOSTICS

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