pcp-summary(1) — Linux manual page


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 [-LPV?]  [-a archive] [-h host] [-O origin] [-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

       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.


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

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

       For environment variables affecting PCP tools, see pmGetOptions(3).

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), pcp.env(5) and PMNS(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2020-11-01.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-10-30.)  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)