--- name: "PCPIntro" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/PCPIntro" --- # PCPIntro(1) introduction to the Performance Co-Pilot (PCP) ## NAME **PCPIntro** - introduction to the Performance Co-Pilot (PCP) ## INTRODUCTION 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, macOS, 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 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)](/pmcd/1.md)) on the same host. Client applications (the monitoring tools) connect to [**pmcd**(1)](/pmcd/1.md), 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)](/pmlogger/1.md)) 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 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)](/pmlogger/1.md). See [**LOGIMPORT**(3)](/LOGIMPORT/3.md) and [**LOGARCHIVE**(5)](/LOGARCHIVE/5.md) 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)](/pmlogger/1.md), 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)](/bzip2/1.md)) or *myarchive***.0.gz** or *myarchive***.0.Z** or *myarchive***.0.z** (the first data volume compressed with [**gzip**(1)](/gzip/1.md)), *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)](/environ/7.md). - **-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)](/pmdbg/1.md) 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 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)](/strtod/3.md)) 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 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)](/pmtime/1.md) 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)](/tzselect/8.md) 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)](/datetime/3.md), 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 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)](/pmcd/1.md) for live monitoring or from a set of PCP archives for retrospective monitoring. To explore the PMNS use [**pminfo**(1)](/pminfo/1.md), or if the PCP GUI package is installed the New Chart and Metric Search windows within [**pmchart**(1)](/pmchart/1.md). 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 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)](/pmcd/1.md) 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)](/pmNewContext/3.md). ## SECURE PMCD CONNECTIONS Since PCP version 3.6.11, a monitor can explicitly request a secure connection to a collector host running [**pmcd**(1)](/pmcd/1.md) or [**pmproxy**(1)](/pmproxy/1.md) 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)](/openssl/1.md) 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 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)](/pmcd/1.md) 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)](/pmcd/1.md) 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)](/pmproxy/1.md) 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)](/pmproxy/1.md) connection through a firewall, and with IPv6 and IPv4 addresses as shown. ``` $ pcp --host nas1.acme.com:44321,4321@firewall.acme.com:44322 $ pcp --host nas1.acme.com:44321@firewall.acme.com:44322 $ pcp --host nas1.acme.com:44321@firewall.acme.com $ pcp --host nas1.acme.com@firewall.acme.com $ 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://nas2.acme.com@firewalls.r.us?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 - */etc/pcp.conf* Configuration file for the PCP runtime environment, see [**pcp.conf**(5)](/pcp.conf/5.md). - */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)](/pmchart/1.md). - *$PCP\_RC\_DIR/pmcd* Script for starting and stopping [**pmcd**(1)](/pmcd/1.md). - *$PCP\_PMCDCONF\_PATH* Control file for [**pmcd**(1)](/pmcd/1.md). - *$PCP\_PMCDOPTIONS\_PATH* Command line options passed to [**pmcd**(1)](/pmcd/1.md) when it is started from **$PCP\_RC\_DIR/pmcd**. 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)](/pmcd/1.md), current directory for running PMDAs. Archives generated by [**pmlogger**(1)](/pmlogger/1.md) are generally below **$PCP\_LOG\_DIR/pmlogger**. - *$PCP\_LOG\_DIR/pmcd/pmcd.log* Diagnostic and status log for the current running [**pmcd**(1)](/pmcd/1.md) 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)](/pmcd/1.md) instance. - *$PCP\_LOG\_DIR/NOTICES* Log of [**pmcd**(1)](/pmcd/1.md) and PMDA starts, stops, additions and removals. - *$PCP\_VAR\_DIR/config* Contains directories of configuration files for several PCP tools. - *$PCP\_SERVICES\_DIR/local* Local script for controlling PCP boot, shutdown and restart actions. This was formerly located in *$PCP\_SYSCONF\_DIR/pmcd/rc.local* and a symbolic link is installed for that name to provide compatibility. - *$PCP\_VAR\_DIR/pmns* Directory containing the set of PMNS files for all installed PMDAs. - *$PCP\_VAR\_DIR/pmns/root* The ASCII [**PMNS**(5)](/PMNS/5.md) exported by [**pmcd**(1)](/pmcd/1.md) 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)](/pmcd/1.md) and PMDA activity, may be used to log alarms and notices from [**pmie**(1)](/pmie/1.md) via [**pmpost**(1)](/pmpost/1.md). - *$PCP\_PMLOGGERCONTROL\_PATH* Control file for [**pmlogger**(1)](/pmlogger/1.md) instances launched from **$PCP\_RC\_DIR/pmlogger** and/or managed by [**pmlogger\_check**(1)](/pmlogger_check/1.md) and [**pmlogger\_daily**(1)](/pmlogger_daily/1.md) as part of a production PCP archive collection setup. ## ENVIRONMENT 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 for applications that use [**pmGetOptions**(3)](/pmGetOptions/3.md) to process command line options and arguments. 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)](/pmdbg/1.md) 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)](/sh/1.md)). 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)](/pmLoadDerivedConfig/3.md), 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)](/pmNewContext/3.md) 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\_DERIVED\_CONTROL** Settings for control options that may be used when processing derived metrics. Refer to [**pmSetDerivedControl**(3)](/pmSetDerivedControl/3.md) for details. - **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)](/pmcd/1.md) is restarted or when multiple archives are concatenated with [**pmlogextract**(1)](/pmlogextract/1.md). These discontinuities are internally noted with a \ record in the PCP archives, and value interpolation as described in [**pmSetMode**(3)](/pmSetMode/3.md) is not supported across \ records (because the values before and after a \ record are not necessarily from a continuous time series). Sometimes the user knows the data semantics are sound in the region of the \ 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 \ 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 \ records will be ignored if the time gap between the last record before the \ and the first record after the \ 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)](/pmcd/1.md) 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)](/pmcd/1.md), 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)](/pmcd/1.md), 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)](/pmcd/1.md) is started from **$PCP\_RC\_DIR/pmcd** 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)](/pmLoadNameSpace/3.md). 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 be 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)](/pmcd/1.md) and [**pmNewContext**(3)](/pmNewContext/3.md) (for **PM\_CONTEXT\_LOCAL** contexts) when searching for a daemon or DSO PMDA. - **PMCD\_PORT** The TCP/IP port(s) used by [**pmcd**(1)](/pmcd/1.md) 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)](/pmlogger/1.md), 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)](/pmlogger/1.md) to create the socket to which [**pmlc**(1)](/pmlc/1.md) 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)](/pmlc/1.md) connects to [**pmlogger**(1)](/pmlogger/1.md), 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)](/pmcd/1.md) 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)](/pmcd/1.md) 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. - **PCP\_PMCDCONF\_PATH** Overrides the path to the [**pmcd**(1)](/pmcd/1.md) configuration file. When set to *$PCP\_SYSCONF\_DIR/local.conf*, a **PM\_CONTEXT\_LOCAL** context will load only the DSO PMDAs listed in that file, without requiring [**pmcd**(1)](/pmcd/1.md) to be running. This is the recommended way to restrict local context to a minimal, well-known set of DSO PMDAs. Pair with **PMNS\_DEFAULT** (below) for a matching namespace. - **PMNS\_DEFAULT** Overrides the default Performance Metrics Name Space used when no explicit namespace is specified. When set to *$PCP\_VAR\_DIR/pmns/local.root*, a **PM\_CONTEXT\_LOCAL** context will use the merged namespace for the DSO PMDAs listed in *$PCP\_SYSCONF\_DIR/local.conf*, rather than the full system namespace. See also [**pmns**(5)](/pmns/5.md) and **PMNS\_DEFAULT** in [**pcpintro**(1)](/pcpintro/1.md). - **PMIECONF\_PATH** If set, [**pmieconf**(1)](/pmieconf/1.md) will form its [**pmieconf**(5)](/pmieconf/5.md) specification (set of parameterized [**pmie**(1)](/pmie/1.md) 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 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)](/pcp.conf/5.md). For environment variables affecting PCP tools, see [**pmGetOptions**(3)](/pmGetOptions/3.md). ## SEE ALSO [**pcp**(1)](/pcp/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmie**(1)](/pmie/1.md), [**pmie\_daily**(1)](/pmie_daily/1.md), [**pminfo**(1)](/pminfo/1.md), [**pmlc**(1)](/pmlc/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmlogger\_daily**(1)](/pmlogger_daily/1.md), [**pmrep**(1)](/pmrep/1.md), [**pmstat**(1)](/pmstat/1.md), [**pmval**(1)](/pmval/1.md), [**systemctl**(1)](/systemctl/1.md), [**LOGIMPORT**(3)](/LOGIMPORT/3.md), [**LOGARCHIVE**(5)](/LOGARCHIVE/5.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md), [**PMNS**(5)](/PMNS/5.md) and [**chkconfig**(8)](/chkconfig/8.md). If the PCP GUI package is installed, then the following entries are also relevant:\ [**pmchart**(1)](/pmchart/1.md), [**pmtime**(1)](/pmtime/1.md), and [**pmdumptext**(1)](/pmdumptext/1.md). 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/**.