pcpintro(1) — Linux manual page

NAME | INTRODUCTION | OVERVIEW | COMMON COMMAND LINE ARGUMENTS | INTERVAL SPECIFICATION AND ALIGNMENT | TIME WINDOW SPECIFICATION | PERFORMANCE METRICS - IDENTIFIERS, NAMES, VALUES | PERFORMANCE METRIC SPECIFICATIONS | SECURE PMCD CONNECTIONS | PMCD HOST SPECIFICATION | FILES | ENVIRONMENT | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PCPINTRO(1)              General Commands Manual             PCPINTRO(1)

NAME         top

       PCPIntro - introduction to the Performance Co-Pilot (PCP)

INTRODUCTION         top

       The Performance Co-Pilot (PCP) is a toolkit designed for
       monitoring and managing system-level performance.  These services
       are distributed and scalable to accommodate the most complex
       system configurations and performance problems.

       PCP supports many different platforms, including (but not limited
       to) Linux, MacOSX, Solaris and Windows.  From a high-level PCP
       can be considered to contain two classes of software utility:

       PCP Collectors
               These are the parts of PCP that collect and extract
               performance data from various sources, for example the
               operating system kernel.

       PCP Monitors
               These are the parts of PCP that display data collected
               from hosts (or archives) that have the PCP Collector
               installed.  Many monitor tools are available as part of
               the core PCP release, while other (typically graphical)
               monitoring tools are available separately in the PCP GUI
               package.

       This manual entry describes the high-level features and options
       common to most PCP utilities available on all platforms.

OVERVIEW         top

       The PCP architecture is distributed in the sense that any PCP
       tool may be executing remotely.  On the host (or hosts) being
       monitored, each domain of performance metrics, whether the
       kernel, a service layer, a database management system, a web
       server, an application, etc.  requires a Performance Metrics
       Domain Agent (PMDA) which is responsible for collecting
       performance measurements from that domain.  All PMDAs are
       controlled by the Performance Metrics Collector Daemon (pmcd(1))
       on the same host.

       Client applications (the monitoring tools) connect to pmcd(1),
       which acts as a router for requests, by forwarding requests to
       the appropriate PMDA and returning the responses to the clients.
       Clients may also access performance data from sets of PCP
       archives (created using pmlogger(1)) for retrospective analysis.

   Security philosophy
       PCP redistributes a wealth of performance information within a
       host and across its networks.  The following security philosophy
       underlies the setting of several defaults that control how much
       information is sent and received.

       By default, the information exposed by PMCD about a host is
       approximately of the same level of confidentiality as available
       to a completely unprivileged user on that host.  So, performance
       data that is available to be read completely freely on a machine
       may be made available by PMCD to the network.

       However, the host running PMCD and its network is not assumed to
       run only friendly applications.  Therefore, write type
       operations, including from the local host, are not permitted by
       default.

       These defaults may be overridden (expanded or reduced) in several
       ways, including by specifying network ACLs in pmcd.conf,
       activating non-default PMDAs, or by using PMCD connections that
       pass user credentials.  For example, some PMDAs automatically
       provide greater information for particular credentialed users or
       groups.

   Applications
       The following performance monitoring applications are primarily
       console based, typically run directly from the command line, and
       are just a small subset of the tools available as part of the
       base PCP package.

       Each tool or command is documented completely in its own
       reference page.

       pmstat Outputs an ASCII high-level summary of system performance.

       pmie   An inference engine that can evaluate predicate-action
              rules to perform alarms and automate system management
              tasks.

       pminfo Interrogate specific performance metrics and the metadata
              that describes them.

       pmlogger
              Generates PCP archives of performance metrics suitable for
              replay by most PCP tools.

       pmrep  Highly customizable performance metrics reporter with
              support for various different output modes.

       pmval  Simple periodic reporting for some or all instances of a
              performance metric, with optional VCR time control.

       If the PCP GUI package is installed then the following additional
       tools are available.

       pmchart
              Displays trends over time of arbitrarily selected
              performance metrics from one or more hosts.

       pmtime Time control utility for coordinating the time between
              multiple tools (including pmchart and pmval).

       pmdumptext
              Produce ASCII reports for arbitrary combinations of
              performance metrics.

COMMON COMMAND LINE ARGUMENTS         top

       There is a set of common command line arguments that are used
       consistently by most PCP tools.

       -a archive, --archive=archive
              Performance metric information is retrospectively
              retrieved from the set of Performance Co-Pilot (PCP)
              archives identified by archive previously generated by
              pmlogger(1).  See LOGIMPORT(3) and LOGARCHIVE(5) for
              archive creation interfaces and format documentation.

              archive is a comma-separated list of names, each of which
              may be the name of a directory containing one or more
              archives, the base name common to all of the physical
              files created by an instance of pmlogger(1), or any one of
              the physical files, e.g.  /path/to/myarchives (directory)
              or myarchive (base name) or myarchive.meta (the metadata
              file) or myarchive.index (the temporal index) or
              myarchive.0 (the first data volume of archive) or
              myarchive.0.bz2 or myarchive.0.bz (the first data volume
              compressed with bzip2(1)) or myarchive.0.gz or
              myarchive.0.Z or myarchive.0.z (the first data volume
              compressed with gzip(1)), myarchive.1 or myarchive.3.bz2
              or myarchive.42.gz etc.

       -h host, --host=host
              Unless directed to another host by the -h (or --host)
              option, or to a set of archives by the -a (or --archive)
              option, the source of performance metrics will be the
              Performance Metrics Collector Daemon (PMCD) on the local
              host.  Refer to the PMCD HOST SPECIFICATION section later
              for further details on the many options available when
              forming the host specification, as well as a detailed
              description of the default local host connection.  The -a
              (or --archive), and -h (or --host) options are mutually
              exclusive.

       -s samples, --samples=samples
              The argument samples defines the number of samples to be
              retrieved and reported.  If samples is 0 or -s (or
              --samples) is not specified, the application will sample
              and report continuously (in real time mode) or until the
              end of the set of PCP archives (in archive mode).

       -z, --hostzone
              Change the reporting timezone to the local timezone at the
              host that is the source of the performance metrics, as
              identified via either the -h (or --host) or -a (or
              --archive) options.

       -Z timezone, --timezone=timezone
              By default, applications report the time of day according
              to the local timezone on the system where the application
              is executed.  The -Z (or --timezone) option changes the
              timezone to timezone in the format of the environment
              variable TZ as described in environ(7).

       -D debugspec, --debug=debugspec
              Sets the PCP debugging options to debugspec to enable
              diagnostics and tracing that is most helpful for
              developers or when trying to diagnose the misbehaviour of
              a PCP application.  debugspec should be a comma-separated
              list of debugging option name(s) and/or decimal integers,
              see pmdbg(1) for a description of the supported option
              names and values.

       In the absence of a live or archive source of metrics, a
       heuristic search for archives for the local host can be invoked
       via the -O (or --origin) option.  When using this option without
       an explicit source of metrics, monitor tools attempt to use
       archives from a system archive location such as
       $PCP_LOG_DIR/pmlogger/`hostname`.  Refer to the TIME WINDOW
       SPECIFICATION section below for details on the acceptable syntax
       for the origin option, but a typical invocation in this mode
       would be -O today or --origin yesterday.

INTERVAL SPECIFICATION AND ALIGNMENT         top

       Most PCP tools operate with periodic sampling or reporting, and
       the -t (or --interval) and -A (or --align) options may be used to
       control the duration of the sample interval and the alignment of
       the sample times.

       -t interval, --interval=interval
              Set the update or reporting interval.

              The interval argument is specified as a sequence of one or
              more elements of the form
                        number[units]
              where number is an integer or floating point constant
              (parsed using strtod(3)) and the optional units is one of:
              seconds, second, secs, sec, s, minutes, minute, mins, min,
              m, hours, hour, h, days, day and d.  If the unit is empty,
              second is assumed.

              In addition, the upper case (or mixed case) version of any
              of the above is also acceptable.

              Spaces anywhere in the interval are ignored, so 4 days 6
              hours 30 minutes, 4day6hour30min, 4d6h30m and 4d6.5h are
              all equivalent.

              Multiple specifications are additive, for example ``1hour
              15mins 30secs'' is interpreted as 3600+900+30 seconds.

       -A align, --align=align
              By default samples are not necessarily aligned on any
              natural unit of time.  The -A or --align option may be
              used to force the initial sample to be aligned on the
              boundary of a natural time unit.  For example -A 1sec, -A
              30min and --align 1hour specify alignment on whole
              seconds, half and whole hours respectively.

              The align argument follows the syntax for an interval
              argument described above for the -t or --interval option.

              Note that alignment occurs by advancing the time as
              required, and that -A (or --align) acts as a modifier to
              advance both the start of the time window (see the next
              section) and the origin time (if the -O or --origin option
              is specified).

TIME WINDOW SPECIFICATION         top

       Many PCP tools are designed to operate in some time window of
       interest, for example to define a termination time for real-time
       monitoring or to define a start and end time within a set of PCP
       archives.

       In the absence of the -O (or --origin) and -A (or --align)
       options to specify an initial sample time origin and time
       alignment (see above), the PCP application will retrieve the
       first sample at the start of the time window.

       The following options may be used to specify a time window of
       interest.

       -S starttime, --start=starttime
              By default the time window commences immediately in real-
              time mode, or coincides with time at the start of the set
              of PCP archives in archive mode.  The -S or --start option
              may be used to specify a later time for the start of the
              time window.

              The starttime parameter may be given in one of three forms
              (interval is the same as for the -t or --interval option
              as described above, datetime is described below):

              interval
                     To specify an offset from the current time (in
                     real-time mode) or the beginning of a set of PCP
                     archives (in archive mode) simply specify the
                     interval of time as the argument.  For example -S
                     30min will set the start of the time window to be
                     exactly 30 minutes from now in real-time mode, or
                     exactly 30 minutes from the start of a set of PCP
                     archives.

              -interval
                     To specify an offset from the end of a set of PCP
                     archives, prefix the interval argument with a minus
                     sign.  In this case, the start of the time window
                     precedes the time at the end of the set of archives
                     by the given interval.  For example -S -1hour will
                     set the start of the time window to be exactly one
                     hour before the time of the last sample in a set of
                     PCP archives.

              @datetime
                     To specify the calendar date and time (local time
                     in the reporting timezone) for the start of the
                     time window, use the datetime syntax preceded by an
                     at sign.  Refer to the datetime description below
                     for detailed information.

       -T endtime, --finish=endtime
              By default the end of the time window is unbounded (in
              real-time mode) or aligned with the time at the end of a
              set of PCP archives (in archive mode).  The -T or --finish
              option may be used to specify an earlier time for the end
              of the time window.

              The endtime parameter may be given in one of three forms
              (interval is the same as for the -t or --interval option
              as described above, datetime is described below):

              interval
                     To specify an offset from the start of the time
                     window simply use the interval of time as the
                     argument.  For example -T 2h30m will set the end of
                     the time window to be 2 hours and 30 minutes after
                     the start of the time window.

              -interval
                     To specify an offset back from the time at the end
                     of a set of PCP archives, prefix the interval
                     argument with a minus sign.  For example -T -90m
                     will set the end of the time window to be 90
                     minutes before the time of the last sample in a set
                     of PCP archives.

              @datetime
                     To specify the calendar date and time (local time
                     in the reporting timezone) for the end of the time
                     window, use the datetime syntax preceded by an at
                     sign.  Refer to the datetime description below for
                     detailed information.

       -O origin, --origin=origin
              By default samples are fetched from the start of the time
              window (see description of -S or --start option) to the
              end of the time window (see description of -T or --finish
              option).  The -O or --origin option allows the
              specification of an origin within the time window to be
              used as the initial sample time.  This is useful for
              interactive use of a PCP tool with the pmtime(1) VCR
              replay facility.

              The origin argument accepted by -O (or --origin) conforms
              to the same syntax and semantics as the starttime argument
              for the -T (or --finish) option.

              For example --origin -0 specifies that the initial
              position should be at the end of the time window; this is
              most useful when wishing to replay ``backwards'' within
              the time window.

       The datetime argument for the -O (or --origin), -S (or --start)
       and -T (or --finish) options consists of:
                 date time zone day relative
       A date can be one of: YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month
       DD YYYY.  A time can be one of: HH:MM:SS, HH:MM.  HH:MM can use
       either the 12 hour (via an am or pm suffix) or 24 hour
       convention.  A day of the week can be a spelled out day of the
       week, optionally preceded by an ordinal number such as second
       Tuesday.  A zone is a time zone value as specified by the
       tzselect(8) command.  A relative time can be a time unit that is:
       preceded by a cardinal number such as 1 year or 2 months,
       preceded by one of the time words this or last, or succeeded by
       the time word ago.  A relative time can also be one of the time
       words: yesterday, today, tomorrow, now.  Examples of datetime
       strings are: 1996-03-04 13:07:47 EST Mon, 1996-03-05 14:07:47 EST
       -1hour, Mon Mar  4 13:07:47 1996, Mar 4 1996, Mar 4, Mar,
       13:07:50 or 13:08.

       For any missing low order fields, the default value of 0 is
       assumed for hours, minutes and seconds, 1 for day of the month
       and Jan for months.  Hence, the following are equivalent: --start
       '@ Mar 1996' and --start '@ Mar 1 00:00:00 1996'.

       If any high order fields are missing, they are filled in by
       starting with the year, month and day from the current time
       (real-time mode) or the time at the beginning of the set of PCP
       archives (archive mode) and advancing the time until it matches
       the fields that are specified.  So, for example if the time
       window starts by default at ``Mon Mar 4 13:07:47 1996'', then
       --start @13:10 corresponds to 13:10:00 on Mon Mar 4, 1996, while
       --start @10:00 corresponds to 10:00:00 on Tue Mar 5, 1996 (note
       this is the following day).

       For greater precision than afforded by datetime(3), the seconds
       component may be a floating point number.

       If a timezone is not included in a datetime then there are
       several interpretations available depending on the other command
       line options used.  The default is to use the local timezone on
       the system where the PCP tool is being run.  A -Z or --timezone
       option specifies an explicit timezone, else a -z or --hostzone
       option changes the timezone to the local timezone at the host
       that is the source of the performance metrics.

PERFORMANCE METRICS - IDENTIFIERS, NAMES, VALUES         top

       The number of performance metric names supported by PCP on most
       platforms ranges from many hundreds to several thousand.  The PCP
       libraries and applications use an internal identification scheme
       that unambiguously associates a single integer with each known
       performance metric.  This integer is known as the Performance
       Metric Identifier, or PMID.  Although not a requirement, PMIDs
       tend to have global consistency across all systems, so a
       particular performance metric usually has the same PMID.

       For all users and most applications, direct use of the PMIDs
       would be inappropriate (this would limit the range of accessible
       metrics, make the code hard to maintain, force the user interface
       to be particularly baroque, and so on).  Hence a Performance
       Metrics Name Space (PMNS) is used to provide external names and a
       hierarchic classification for performance metrics.  A PMNS is
       represented as a tree, with each node having a label, a pointer
       to either a PMID (for leaf nodes) or a set of descendent nodes in
       the PMNS (for non-leaf nodes).

       A node label must begin with an alphabetic character, followed by
       zero or more characters drawn from the alphabetics, the digits
       and character ``_'' (underscore).  For alphabetic characters in a
       node label, upper and lower case are distinguished.

       By convention, the name of a performance metric is constructed by
       concatenation of the node labels on a path through the PMNS from
       the root node to a leaf node, with a ``.'' as a separator.  The
       root node in the PMNS is unlabeled, so all names begin with the
       label associated with one of the descendent nodes below the root
       node of the PMNS, for example kernel.percpu.syscall.  Typically
       (although this is not a requirement) there would be at most one
       name for each PMID in a PMNS.  For example kernel.all.cpu.idle
       and disk.dev.read are the unique names for two distinct
       performance metrics, each with a unique PMID.

       Groups of related PMIDs may be named by naming a non-leaf node in
       the PMNS tree, for example disk.

       The default local PMNS used by pmcd is located at
       $PCP_VAR_DIR/pmns/root however the environment variable
       PMNS_DEFAULT may be set to the full pathname of a different PMNS
       which will then be used as the default local PMNS.

       Most applications do not use the local PMNS directly, but rather
       import parts of the PMNS as required from the same place that
       performance metrics are fetched, i.e. from pmcd(1) for live
       monitoring or from a set of PCP archives for retrospective
       monitoring.

       To explore the PMNS use pminfo(1), or if the PCP GUI package is
       installed the New Chart and Metric Search windows within
       pmchart(1).

       Some performance metrics have a singular value.  For example, the
       available memory or number of context switches have one value per
       performance metric source, that is, one value per host.  The
       metric descriptor (metadata) for each metric makes this fact
       known to applications that process values for these single-valued
       metrics.

       Some performance metrics have a set of values or instances in
       each implementing performance metric domain.  For example, one
       value for each disk, one value for each process, one value for
       each CPU, or one value for each activation of a given
       application.  When a metric has multiple instances, the PMNS does
       not represent this in metric names; rather, a single metric may
       have an associated set of values.  Multiple values are associated
       with the members of an instance domain, such that each instance
       has a unique instance identifier within the associated instance
       domain.  For example, the ''per CPU´´ instance domain may use the
       instance identifiers 0, 1, 2, 3, and so on to identify the
       configured processors in the system.  Internally, instance
       identifiers are encoded as binary values, but each performance
       metric domain also supports corresponding strings as external
       names for the instance identifiers, and these names are used at
       the user interface to the PCP utilities.

       Multiple performance metrics may be associated with a single
       instance domain.  For example, per-process metrics under proc all
       share the same instance domain.

       PCP arranges for information describing instance domains to be
       exported from the performance metric domains to the applications
       that require this information.  Applications may also choose to
       retrieve values for all instances of a performance metric, or
       some arbitrary subset of the available instances.

       Metric names and the instance domain concept provides two-
       dimensions for the modelling of performance metrics.  This is a
       clear and simple model, however on some occasions it does not
       suffice.  For example, a metric may wish to represent higher
       dimensional data such as ``per CPU'' counters for each running
       process.  In these cases it is common to create a compound
       instance, where the name is composed of each component with a
       separator in-between (for example, ``87245::cpu7'' might be used
       to separate process ID from CPU ID) to create flattened instance
       names.  Additionally, such cases benefit from the use of metric
       instances labels to explicitly show the separate components
       (continuing the example from above, labels
       ``{"pid":87245,"cpu":7}'' might be used).

PERFORMANCE METRIC SPECIFICATIONS         top

       In configuration files and (to a lesser extent) command line
       options, metric specifications adhere to the following syntax
       rules by most tools.  See the tool specific manual pages for the
       exact syntax supported.

       If the source of performance metrics is real-time from pmcd(1)
       then the accepted syntax is
                 host:metric[instance1,instance2,...]

       If the source of performance metrics is a set of PCP archives
       then the accepted syntax is
                 archive/metric[instance1,instance2,...]

       The host:, archive/ and [instance1,instance2,...]  components are
       all optional.

       The , delimiter in the list of instance names may be replaced by
       white space.

       Special characters in instance names may be escaped by
       surrounding the name in double quotes or preceding the character
       with a backslash.

       White space is ignored everywhere except within a quoted instance
       name.

       An empty instance is silently ignored, and in particular ``[]''
       is the same as no instance, while ``[one,,,two]'' is parsed as
       specifying just the two instances ``one'' and ``two''.

       As a special case, if the host is the single character ``@'' then
       this refers to a PM_CONTEXT_LOCAL source, see pmNewContext(3).

SECURE PMCD CONNECTIONS         top

       Since PCP version 3.6.11, a monitor can explicitly request a
       secure connection to a collector host running pmcd(1) or
       pmproxy(1) using the PM_CTXFLAG_SECURE context flag.  If the PCP
       Collector host supports this feature - refer to the
       pmcd.feature.secure metric for confirmation of this - a TLS/SSL
       (Transport Layer Security or Secure Sockets Layer) connection can
       be established which uses public key cryptography and related
       techniques.  These features aim to prevent eavesdropping and data
       tampering from a malicious third party, as well as providing
       server-side authentication (confident identification of a server
       by a client) which can be used to guard against man-in-the-middle
       attacks.

       A secure pmcd connection requires use of certificate-based
       authentication.  The security features offered by pmcd and
       pmproxy are implemented using the OpenSSL APIs and utilities.
       The openssl(1) tool can be used to create certificates suitable
       for establishing trust between PCP monitor and collector hosts.

       A complete description is beyond the scope of this document,
       refer to the PCP ENVIRONMENT, FILES and SEE ALSO sections for
       detailed information.  This includes links to tutorials on the
       steps involved in setting up the available security features.

PMCD HOST SPECIFICATION         top

       In the absence of an explicit hostname specification, most tools
       will default to the local host in live update mode.  In PCP
       releases since 3.8.4 onward, this results in an efficient local
       protocol being selected - typically a Unix domain socket.  If
       this option is used (which can also be explicitly requested via
       the unix: host specification described below), it is important to
       note that all connections will be automatically authenticated.
       In other words, the credentials of the user invoking a client
       tool will automatically be made available to pmcd(1) and all of
       its PMDAs, on the users behalf, such that results can be
       customized to the privilege levels of individual users.

       Names of remote hosts running the pmcd(1) daemon can of course
       also be provided to request a remote host be used.  The most
       basic form of pmcd host specification is a simple host name,
       possibly including the domain name if necessary.  However, this
       can be extended in a number of ways to further refine attributes
       of the connection made to pmcd.

       The pmcd port number and also optional pmproxy(1) hostname and
       its port number, can be given as part of the host specification,
       since PCP version 3.0.  These supersede (and override) the old-
       style PMCD_PORT, PMPROXY_HOST and PMPROXY_PORT environment
       variables.

       The following are valid hostname specifications that specify
       connections to pmcd on host nas1.acme.com with/without a list of
       ports, with/without a pmproxy(1) connection through a firewall,
       and with IPv6 and IPv4 addresses as shown.

            $ pcp --host nas1.acme.com:44321,[email protected]:44322
            $ pcp --host nas1.acme.com:[email protected]:44322
            $ pcp --host nas1.acme.com:[email protected]
            $ pcp --host [email protected]
            $ pcp --host nas1.acme.com:44321
            $ pcp --host [fe80::2ad2:44ff:fe88:e4f1%p2p1]
            $ pcp --host 192.168.0.103

       In addition, ``connection attributes'' can also be specified.
       These include username, password (can be given interactively and
       may depend on the authentication mechanism employed), whether to
       target a specific running container, whether to use secure
       (encrypted) or native (naked) protocol, and so on.  The previous
       examples all default to native protocol, and use no
       authentication.  This can be altered, as in the following
       examples.

            $ pcp --host pcps://app2.acme.com?container=cae8e6edc0d5
            $ pcp --host pcps://nas1.acme.com:44321?username=tanya&method=gssapi
            $ pcp --host pcps://[email protected]?method=plain
            $ pcp --host pcp://nas3.acme.com
            $ pcp --host 192.168.0.103?container=cae8e6edc0d5,method=scram-sha-256
            $ pcp --host unix:
            $ pcp --host local:

       The choice of authentication method, and other resulting
       parameters like username, optionally password, etc, depends on
       the SASL2 configuration used by each (remote) pmcd.  Tutorials
       are available specifying various aspects of configuring the
       authentication module(s) used, these fine details are outside the
       scope of this document.

       In all situations, host names can be used interchangeably with
       IPv4 or IPv6 addressing (directly), as shown above.  In the case
       of an IPv6 address, the full address must be enclosed by square
       brackets and the scope (interface) must also be specified.

       The final local: example above is now the default for most tools.
       This connection is an automatically authenticated local host
       connection on all platforms that support Unix domain sockets.  No
       password is required and authentication is automatic.  This is
       also the most efficient (lowest overhead) communication channel.

       The difference between unix: and local: is that the former is a
       strict Unix domain socket specification (connection fails if it
       cannot connect that way), whereas the latter has a more forgiving
       fallback to using localhost (i.e. a regular Inet socket
       connection is used when Unix domain socket connections are
       unavailable).

FILES         top

       /etc/pcp.conf
            Configuration file for the PCP runtime environment, see
            pcp.conf(5).

       /etc/pcp/tls.conf
            Optionally contains OpenSSL configuration information,
            including locations of certificates providing trusted
            identification for collector and monitor hosts.

       $HOME/.pcp
            User-specific directories containing configuration files for
            customisation of the various monitor tools, such as
            pmchart(1).

       $PCP_RC_DIR/pcp
            Script for starting and stopping pmcd(1).

       $PCP_PMCDCONF_PATH
            Control file for pmcd(1).

       $PCP_PMCDOPTIONS_PATH
            Command line options passed to pmcd(1) when it is started
            from $PCP_RC_DIR/pcp.  All the command line option lines
            should start with a hyphen as the first character.  This
            file can also contain environment variable settings of the
            form "VARIABLE=value".

       $PCP_BINADM_DIR
            Location of PCP utilities for collecting and maintaining PCP
            archives, PMDA help text, PMNS files etc.

       $PCP_PMDAS_DIR
            Parent directory of the installation directory for Dynamic
            Shared Object (DSO) PMDAs.

       $PCP_RUN_DIR/pmcd.pid
            If pmcd is running, this file contains an ascii decimal
            representation of its process ID.

       $PCP_LOG_DIR/pmcd
            Default location of log files for pmcd(1), current directory
            for running PMDAs.  Archives generated by pmlogger(1) are
            generally below $PCP_LOG_DIR/pmlogger.

       $PCP_LOG_DIR/pmcd/pmcd.log
            Diagnostic and status log for the current running pmcd(1)
            process.  The first place to look when there are problems
            associated with pmcd.

       $PCP_LOG_DIR/pmcd/pmcd.log.prev
            Diagnostic and status log for the previous pmcd(1) instance.

       $PCP_LOG_DIR/NOTICES
            Log of pmcd(1) and PMDA starts, stops, additions and
            removals.

       $PCP_VAR_DIR/config
            Contains directories of configuration files for several PCP
            tools.

       $PCP_SYSCONF_DIR/pmcd/rc.local
            Local script for controlling PCP boot, shutdown and restart
            actions.

       $PCP_VAR_DIR/pmns
            Directory containing the set of PMNS files for all installed
            PMDAs.

       $PCP_VAR_DIR/pmns/root
            The ASCII PMNS(5) exported by pmcd(1) by default.  This PMNS
            is be the super set of all other PMNS files installed in
            $PCP_VAR_DIR/pmns.

       In addition, if the PCP product is installed the following files
       and directories are relevant.

       $PCP_LOG_DIR/NOTICES
              In addition to the pmcd(1) and PMDA activity, may be used
              to log alarms and notices from pmie(1) via pmpost(1).

       $PCP_PMLOGGERCONTROL_PATH
              Control file for pmlogger(1) instances launched from
              $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1) and
              pmlogger_daily(1) as part of a production PCP archive
              collection setup.

ENVIRONMENT         top

       In addition to the PCP run-time environment and configuration
       variables described in the PCP ENVIRONMENT section below, the
       following environment variables apply to all installations.

       Note that most uses of these environment variables are optimized
       to check the environment only the first time the variable might
       be used.  As the environment usually is not checked again, the
       only safe strategy is to ensure all PCP-related environment
       variables are set before the first call into any of the PCP
       libraries.

       PCP_ALLOW_BAD_CERT_DOMAIN
              When set, allow clients to accept certificates with
              mismatched domain names with no prompt when they are sent
              by pmcd or other server components.  See
              PCP_SECURE_SOCKETS.

       PCP_ALLOW_SERVER_SELF_CERT
              When set, allow clients to accept self-signed certificates
              with no prompt when they are sent by pmcd or other server
              components.  See PCP_SECURE_SOCKETS.

       PCP_CONSOLE
              When set, this changes the default console from /dev/tty
              (on Unix) or CON: (on Windows) to be the specified
              console.  The special value of none can be used to
              indicate no console is available for use.  This is used in
              places where console-based tools need to interact with the
              user, and in particular is used when authentication is
              being performed.

       PCP_DEBUG
              When set, this variable provides an alternate to the -D
              command line option described above to initialize the
              diagnostic and debug options.  The value for $PCP_DEBUG is
              the same as for the -D command line option, namely a
              comma-separated list of debugging option name(s), and/or
              decimal integers, see pmdbg(1) for a description of the
              supported option names and values.

       PCP_DERIVED_CONFIG
              When set, this variable defines a colon separated list of
              files and/or directories (the syntax is the same as for
              the $PATH variable for sh(1)).  The components are
              expanded into a list of files as follows: if a component
              of $PCP_DERIVED_CONFIG is a file, then that file is added
              to the list, else if a component is a directory then
              recursive descent is used to enumerate all files below
              that directory and these are added to the list.

              Each file in the resulting list is assumed to contain
              definitions of derived metrics as per the syntax described
              in pmLoadDerivedConfig(3), and these are loaded in order.

              Derived metrics may be used to extend the available
              metrics with new (derived) metrics using simple arithmetic
              expressions.

              If PCP_DERIVED_CONFIG is set, the derived metric
              definitions are processed automatically as each new source
              of performance metrics is established (i.e. each time a
              pmNewContext(3) is called) or when requests are made
              against the PMNS.

              Any component in the $PCP_DERIVED_CONFIG list or the
              expanded list of files that is not a file, or is not a
              directory or is not accessible (due to permissions or a
              bad symbolic link) will be silently ignored.

       PCP_IGNORE_MARK_RECORDS
              When PCP archives logs are created there may be temporal
              gaps associated with discontinuities in the time series of
              logged data, for example when pmcd(1) is restarted or when
              multiple archives are concatenated with pmlogextract(1).
              These discontinuities are internally noted with a <mark>
              record in the PCP archives, and value interpolation as
              described in pmSetMode(3) is not supported across <mark>
              records (because the values before and after a <mark>
              record are not necessarily from a continuous time series).
              Sometimes the user knows the data semantics are sound in
              the region of the <mark> records, and
              $PCP_IGNORE_MARK_RECORDS may be used to suppress the
              default behaviour.

              If PCP_IGNORE_MARK_RECORDS is set (but has no value) then
              all <mark> records will be ignored.  Otherwise the value
              $PCP_IGNORE_MARK_RECORDS follows the syntax for an
              interval argument described above for the -t option, and
              <mark> records will be ignored if the time gap between the
              last record before the <mark> and the first record after
              the <mark> is not more than interval.

       PCP_SECURE_SOCKETS
              When set, this variable forces any monitor tool
              connections to be established using the certificate-based
              secure sockets feature.  If the connections cannot be
              established securely, they will fail.

       PCP_TLSCONF_PATH
              Specifies the location from which TLS (Transport Layer
              Security) configuration settings will be read.  These
              settings are used by PCP client tools, pmcd and pmproxy
              whenever secure (encrypted) communication is requested.

       PCP_STDERR
              Many PCP tools support the environment variable
              PCP_STDERR, which can be used to control where error
              messages are sent.  When unset, the default behavior is
              that ``usage'' messages and option parsing errors are
              reported on standard error, other messages after initial
              startup are sent to the default destination for the tool,
              i.e. standard error for ASCII tools, or a dialog for GUI
              tools.

              If PCP_STDERR is set to the literal value DISPLAY then all
              messages will be displayed in a dialog.  This is used for
              any tools launched from a Desktop environment.

              If PCP_STDERR is set to any other value, the value is
              assumed to be a filename, and all messages will be written
              there.

       PMCD_CONNECT_TIMEOUT
              When attempting to connect to a remote pmcd(1) on a
              machine that is booting, the connection attempt could
              potentially block for a long time until the remote machine
              finishes its initialization.  Most PCP applications and
              some of the PCP library routines will abort and return an
              error if the connection has not been established after
              some specified interval has elapsed.  The default interval
              is 5 seconds.  This may be modified by setting
              PMCD_CONNECT_TIMEOUT in the environment to a real number
              of seconds for the desired timeout.  This is most useful
              in cases where the remote host is at the end of a slow
              network, requiring longer latencies to establish the
              connection correctly.

       PMCD_RECONNECT_TIMEOUT
              When a monitor or client application loses a connection to
              a pmcd(1), the connection may be re-established by calling
              a service routine in the PCP library.  However, attempts
              to reconnect are controlled by a back-off strategy to
              avoid flooding the network with reconnection requests.  By
              default, the back-off delays are 5, 10, 20, 40 and 80
              seconds for consecutive reconnection requests from a
              client (the last delay will be repeated for any further
              attempts after the fifth).  Setting the environment
              variable PMCD_RECONNECT_TIMEOUT to a comma separated list
              of positive integers will re-define the back-off delays,
              for example setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will
              back-off for 1 second, then attempt another connection
              request every 2 seconds thereafter.

       PMCD_REQUEST_TIMEOUT
              For monitor or client applications connected to pmcd(1),
              there is a possibility of the application "hanging" on a
              request for performance metrics or metadata or help text.
              These delays may become severe if the system running pmcd
              crashes, or the network connection is lost.  By setting
              the environment variable PMCD_REQUEST_TIMEOUT to a number
              of seconds, requests to pmcd will timeout after this
              number of seconds.  The default behavior is to be willing
              to wait 10 seconds for a response from every pmcd for all
              applications.

       PMCD_WAIT_TIMEOUT
              When pmcd(1) is started from $PCP_RC_DIR/pcp then the
              primary instance of pmlogger(1) will be started if the
              configuration flag pmlogger is chkconfig(8) or
              systemctl(1) enabled and pmcd is running and accepting
              connections.

              The check on pmcd's readiness will wait up to
              PMCD_WAIT_TIMEOUT seconds.  If pmcd has a long startup
              time (such as on a very large system), then
              PMCD_WAIT_TIMEOUT can be set to provide a maximum wait
              longer than the default 60 seconds.

       PMNS_DEFAULT
              If set, then interpreted as the full pathname to be used
              as the default local PMNS for pmLoadNameSpace(3).
              Otherwise, the default local PMNS is located at
              $PCP_VAR_DIR/pcp/pmns/root for base PCP installations.

       PCP_COUNTER_WRAP
              Many of the performance metrics exported from PCP agents
              have the semantics of counter meaning they are expected to
              be monotonically increasing.  Under some circumstances,
              one value of these metrics may smaller than the previously
              fetched value.  This can happen when a counter of finite
              precision overflows, or when the PCP agent has been reset
              or restarted, or when the PCP agent is exporting values
              from some underlying instrumentation that is subject to
              some asynchronous discontinuity.

              The environment variable PCP_COUNTER_WRAP may be set to
              indicate that all such cases of a decreasing ``counter''
              should be treated as a counter overflow, and hence the
              values are assumed to have wrapped once in the interval
              between consecutive samples.  This ``wrapping'' behavior
              was the default in earlier PCP versions, but by default
              has been disabled in PCP release from version 1.3 on.

       PCP_PMDAS_DIR
              The PCP_PMDAS_DIR environment variable may be used to
              modify the directory used by pmcd(1) and pmNewContext(3)
              (for PM_CONTEXT_LOCAL contexts) when searching for a
              daemon or DSO PMDA.

       PMCD_PORT
              The TCP/IP port(s) used by pmcd(1) to create the socket
              for incoming connections and requests, was historically
              4321 and more recently the officially registered port
              44321; in the current release, both port numbers are used
              by default as a transitional arrangement.  This may be
              over-ridden by setting PMCD_PORT to a different port
              number, or a comma-separated list of port numbers.  If a
              non-default port is used when pmcd is started, then every
              monitoring application connecting to that pmcd must also
              have PMCD_PORT set in their environment before attempting
              a connection.

       The following environment variables are relevant to installations
       in which pmlogger(1), the PCP archiver, is used.

       PMLOGGER_PORT
              The environment variable PMLOGGER_PORT may be used to
              change the base TCP/IP port number used by pmlogger(1) to
              create the socket to which pmlc(1) instances will try and
              connect.  The default base port number is 4330.  When
              used, PMLOGGER_PORT should be set in the environment
              before pmlogger is executed.

       PMLOGGER_REQUEST_TIMEOUT
              When pmlc(1) connects to pmlogger(1), there is a remote
              possibility of pmlc "hanging" on a request for information
              as a consequence of a failure of the network or pmlogger.
              By setting the environment variable
              PMLOGGER_REQUEST_TIMEOUT to a number of seconds, requests
              to pmlogger will timeout after this number of seconds.
              The default behavior is to be willing to wait forever for
              a response from each request to a pmlogger.  When used,
              PMLOGGER_REQUEST_TIMEOUT should be set in the environment
              before pmlc is executed.

       If you have the PCP product installed, then the following
       environment variables are relevant to the Performance Metrics
       Domain Agents (PMDAs).

       PMDA_LOCAL_PROC
              Use this variable has been deprecated and it is now
              ignored.  If the ``proc'' PMDA is configured as a DSO for
              use with pmcd(1) on the local host then all of the
              ``proc'' metrics will be available to applications using a
              PM_CONTEXT_LOCAL context.

              The previous behaviour was that if this variable was set,
              then a context established with the type of
              PM_CONTEXT_LOCAL will have access to the ``proc'' PMDA to
              retrieve performance metrics about individual processes.

       PMDA_LOCAL_SAMPLE
              Use this variable has been deprecated and it is now
              ignored.  If the ``sample'' PMDA is configured as a DSO
              for use with pmcd(1) on the local host then all of the
              ``sample'' metrics will be available to applications using
              a PM_CONTEXT_LOCAL context.

              The previous behaviour was that if this variable was set,
              then a context established with the type of
              PM_CONTEXT_LOCAL will have access to the ``sample'' PMDA
              if this optional PMDA has been installed locally.

       PMIECONF_PATH
              If set, pmieconf(1) will form its pmieconf(5)
              specification (set of parameterized pmie(1) rules) using
              all valid pmieconf files found below each subdirectory in
              this colon-separated list of subdirectories.  If not set,
              the default is $PCP_VAR_DIR/config/pmieconf.

PCP ENVIRONMENT         top

       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

       pcp(1), pmcd(1), pmie(1), pmie_daily(1), pminfo(1), pmlc(1),
       pmlogger(1), pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1),
       systemctl(1), LOGIMPORT(3), LOGARCHIVE(5), pcp.conf(5),
       pcp.env(5), PMNS(5) and chkconfig(8).

       If the PCP GUI package is installed, then the following entries
       are also relevant:
       pmchart(1), pmtime(1), and pmdumptext(1).

       If the secure sockets extensions have been enabled, then the
       following references are also relevant:
       https://pcp.io/documentation.html 
       https://pcp.readthedocs.io/en/latest/QG/EncryptedConnections.html 
       https://pcp.readthedocs.io/en/latest/QG/AuthenticatedConnections.html 

       Also refer to the books Performance Co-Pilot User's and
       Administrator's Guide and Performance Co-Pilot Programmer's Guide
       which can be found at https://pcp.readthedocs.io/en/latest/ .

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 [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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
       [email protected]

Performance Co-Pilot               PCP                       PCPINTRO(1)

Pages that refer to this page: autofsd-probe(1)collectl2pcp(1)dbprobe(1)htop(1)indomcachectl(1)mkaf(1)pcp(1)pcp2arrow(1)pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2openmetrics(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pcp-atop(1)pcp-atopsar(1)pcp-check(1)pcp-dmcache(1)pcp-dstat(1)pcp-free(1)pcp-geolocate(1)pcp-iostat(1)pcp-ipcs(1)pcp-meminfo(1)pcp-mpstat(1)pcp-netstat(1)pcp-numastat(1)pcp-pidstat(1)pcp-ps(1)pcp-python(1)pcp-reboot-init(1)pcp-shping(1)pcp-slabinfo(1)pcp-ss(1)pcp-tapestat(1)pcp-uptime(1)pcp-verify(1)pcp-zoneinfo(1)pmcd(1)pmcd_wait(1)pmchart(1)pmclient(1)pmdaactivemq(1)pmdaapache(1)pmdabcc(1)pmdabind2(1)pmdabonding(1)pmdabpf(1)pmdabpftrace(1)pmdacifs(1)pmdadbping(1)pmdadenki(1)pmdadm(1)pmdadocker(1)pmdads389(1)pmdads389log(1)pmdaelasticsearch(1)pmdafarm(1)pmdagfs2(1)pmdagluster(1)pmdagpfs(1)pmdahacluster(1)pmdahaproxy(1)pmdaib(1)pmdajbd2(1)pmdajson(1)pmdakernel(1)pmdakvm(1)pmdalibvirt(1)pmdalio(1)pmdalmsensors(1)pmdalogger(1)pmdalustre(1)pmdalustrecomm(1)pmdamailq(1)pmdamemcache(1)pmdamic(1)pmdammv(1)pmdamongodb(1)pmdamounts(1)pmdamssql(1)pmdamysql(1)pmdanetcheck(1)pmdanetfilter(1)pmdanfsclient(1)pmdanginx(1)pmdanutcracker(1)pmdanvidia(1)pmdaopenmetrics(1)pmdaopenvswitch(1)pmdaoracle(1)pmdaoverhead(1)pmdaperfevent(1)pmdapipe(1)pmdapodman(1)pmdapostfix(1)pmdapostgresql(1)pmdaproc(1)pmdarabbitmq(1)pmdaredis(1)pmdaresctrl(1)pmdaroomtemp(1)pmdaroot(1)pmdarsyslog(1)pmdasample(1)pmdasendmail(1)pmdashping(1)pmdasimple(1)pmdaslurm(1)pmdasmart(1)pmdasockets(1)pmdastatsd(1)pmdasummary(1)pmdasystemd(1)pmdatrace(1)pmdatrivial(1)pmdatxmon(1)pmdaunbound(1)pmdauwsgi(1)pmdaxfs(1)pmdazfs(1)pmdazimbra(1)pmdazswap(1)pmdbg(1)pmdiff(1)pmdumptext(1)pmfind(1)pmfind_check(1)pmgetopt(1)pmie(1)pmie2col(1)pmie_check(1)pmieconf(1)pminfo(1)pmlc(1)pmlogcheck(1)pmlogctl(1)pmlogdump(1)pmlogextract(1)pmlogger(1)pmlogger_check(1)pmlogger_daily(1)pmlogger_daily_report(1)pmlogger_merge(1)pmlogger_rewrite(1)pmloglabel(1)pmlogmv(1)pmlogpaste(1)pmlogreduce(1)pmlogrewrite(1)pmlogsize(1)pmlogsummary(1)pmprobe(1)pmproxy(1)pmpython(1)pmrep(1)pmsearch(1)pmseries(1)pmsleep(1)pmstat(1)pmtime(1)pmval(1)pmview(1)telnet-probe(1)pcpintro(3)pmaddderived(3)pmaddderivedtext(3)pmapi(3)pmdagetoptions(3)pmderivederrstr(3)pmgetconfig(3)pmgetcontexthostname(3)pmgetderivedcontrol(3)pmgetoptions(3)pmiaddmetric(3)pmloadderivedconfig(3)__pmlogwritemark(3)pmparsehostattrsspec(3)pmparsehostspec(3)pmparseinterval(3)pmparsemetricspec(3)pmparsetimewindow(3)pmregisterderived(3)pmwebapi(3)zbxpcp(3)LOGARCHIVE(5)mmv(5)pcp-atoprc(5)pcp.conf(5)pcp-dstat(5)pcp.env(5)pmlogger.control(5)pmns(5)pmrep.conf(5)