PCP(1)                     General Commands Manual                    PCP(1)

NAME         top

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

SYNOPSIS         top

       pcp [pcp options...]  pcp-command [command options...]
       pcp [-P] [-a archive] [-h host] [-n pmnsfile]

DESCRIPTION         top

       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         top

       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         top

       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

       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 set of PCP
              archive logs, 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
              Report the PCP configuration on host rather than the local

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

                 Per-user location for command scripts.
                 System location for installed command scripts.
                 pmlogconf(1) configuration file for collecting all of the
                 metrics required by pcp.


       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         top

       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         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2019-07-28.  (At that time, the date of the most recent commit that
       was found in the repository was 2019-07-26.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                              PCP(1)

Pages that refer to this page: pcp(1)pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pcp-atop(1)pcp-atopsar(1)pcp-dmcache(1)pcp-dstat(1)pcp-free(1)pcpintro(1)pcp-iostat(1)pcp-mpstat(1)pcp-numastat(1)pcp-pidstat(1)pcp-python(1)pcp-shping(1)pcp-tapestat(1)pcp-uptime(1)pcp-verify(1)pmgetopt(1)pmpython(1)pmrep(1)pmstat(1)pmview(1)pcp-atoprc(5)