PCPIntro man page

Performance Co-Pilot (PCP) is a toolkit designed for monitoring and managing system-level performance.

The PCP libraries support the APIs required to create new performance monitoring tools and new agents (or PMDAs) to export performance data. The libpcp library is used in both cases. The libpcp_pmda library is used only for PMDAs.

Individual library routines are documented in their own manual page entries.

Most routines return an integer value; greater than equal to zero for success and less than zero for an error. The error codes have symbolic names defined in <pcp/pmapi.h>. Other negative values are used to encode errors that can be mapped to the traditional errno values defined in <errno.h>, with the value negated. To translate all PCP error codes into useful messages use either pmerr(1) or pmErrStr(3); the latter may also be used to decode the -errno cases.

Timeout waiting for a response from PMCDMany interactions between PCP applications involve synchronous message passing, and these are subject to timeout constraints. These errors are most frequently encountered when using network connections with slow data rates or long latencies.

For client-pmcd timeouts, refer to PCPIntro(1) for environment variables that may be used to modify the timeout thresholds. For pmcd-PMDA timeouts refer to the -t and -q options of pmcd(1) and the PCP metric pmcd.control.timeout that can be dynamically changed with pmstore(1).

PM_ERR_APPVERSION

Metric not supported by this version of monitored applicationSome performance metrics are unavailable from specific versions of the associated PMDA, or may be unavailable because the underlying instrumentation has changed or is not installed or is not enabled. This error is used in results from pmFetch(3) to indicate these situations.

PM_ERR_IPC

IPC protocol failureGeneric protocol failure on a pipe or socket connecting two PCP applications, eg. client-pmcd, or client-pmtime, or PMDA-pmcd or pmlc-pmlogger.

PM_ERR_TEXT

Oneline or help text is not availableSet by a PMDA, and passed back to a PCP client, to indicate that the PMDA is unable to supply the requested metric or instance domain help text.

PM_ERR_VALUE

Missing metric value(s)This error is used for a number of conditions in which the value of a performance metric is inappropriate for the context in which it is being used, eg.

(a)

Bad value for the metric pmcd.timezone when trying to set the timezone via pmNewContextZone(3) for a remote or archive context.

(b)

Attempting to interpolate values for a metric with non-numeric data type from a set of PCP archives.

Truncation in value conversionSome conversion requests to pmExtractValue(3) cannot be performed based on the metric types and values involved, in this case conversion would result in loss of precision.

PM_ERR_SIGN

Negative value in conversion to unsignedSome conversion requests to pmExtractValue(3) cannot be performed based on the metric types and values involved, in this case converting a negative value to an unsigned value.

PM_ERR_TYPE

Unknown or illegal metric typeThe metric type is held in the metric descriptor and sometimes encoded in the metric values returned from a call to pmFetch(3). Legal values for the metric type are defined by the PM_TYPE_* macros in <pcp/pmapi.h>.

PM_ERR_UNIT

Illegal pmUnits specificationSome conversion requests to pmConvScale(3) cannot be performed due to illegal or incompatible specifications of the source and destination units.

PM_ERR_PROFILE

Explicit instance identifier(s) requiredSome PMDAs, especially the proc PMDA, will not return “all instances” for a pmFetch(3) request due to the cost. The client must explicitly built an instance profile using pmAddProfile(3) and/or pmDelProfile(3) before calling pmFetch(3). See also the -F option to pminfo(1).

PM_ERR_INST

Unknown or illegal instance identifierA request to a PMDA nominates an instance that is unknown. May occur as a consequence of the profile established prior to a pmFetch(3) call, or an explicit instance name or identifier to pmLookupInDom(3) or pmNameInDom(3).

Operation not supported for multi-threaded applicationsAs documented in PMAPI(3) and elsewhere, some libpcp routines are intended solely for use from single-threaded applications.

PM_ERR_TOOBIG

Result size exceededIndicates a fatal error in the message (or PDU) passing protocol between two PCP applications. This is an internal error, and other than an exotic networking failure, should not occur.

PM_ERR_RESET

PMCD reset or configuration changeNot used.

Refer to pmFetch(3) for an alternative mechanism that may be used to notify a PCP client when pmcd(1) has experienced one or more configuration changes since the last request from the client. Usually these changes involve a change to the namespace exported via pmcd and/or changes to the PMDAs under pmcd's control.

PM_ERR_FAULT

QA fault injectedUsed only for PCP Quality Assurance (QA) testing.

PM_ERR_NYI

Functionality not yet implementedSelf explanatory and rarely used.

PM_ERR_GENERIC

Generic error, already reported aboveRarely used, this error may be returned when the error condition is a consequent of some earlier returned error and a more precise characterization is not possible.

These errors may occur in the interactions between a PCP client and pmcd(1) providing real-time performance data.

PM_ERR_NOAGENT

No PMCD agent for domain of requestA request sent to pmcd(1) requires information from an agent or PMDA that does not exist. Usually this means the namespace being used by the client application contains metric names from a previously installed PMDA.

PM_ERR_CONNLIMIT

PMCD connection limit for this host exceededThe client connection limit for pmcd(1) is controlled by the optional access controls in $PCP_PMCDCONF_PATH. By default there is no limit imposed by the PCP code, and this error would not be seen.

PM_ERR_AGAIN

Try again. Information not currently availableUsed to notify a PCP client that the PMDA responsible for delivering the information is temporarily unavailable. See also PM_ERR_PMDANOTREADY.

PM_ERR_NOPROFILE

Missing profile - protocol botchInternal error in the communication between a client application and pmcd(1) - should not occur.

These errors may occur in the interactions between a PCP client and the library routines that provide historical performance data from PCP archives created by pmlogger(1).

PM_ERR_LOGFILE

Missing archive fileEach PCP archive consists of multiple physical files as described in pmlogger(1). This error occurs when one of the physical files is missing or cannot be opened for reading.

PM_ERR_EOL

End of PCP archive logAn attempt is made to read past the end file of the last volume of a set of PCP archives, or past the end of the time window (as specified with a -T option) for a set of PCP archives.

Metric not defined in the PCP archive logA PCP client has requested information about a metric, and there is no corresponding information in the set of PCP archives. This should not happen for well-behaved PCP clients.

PM_ERR_INDOM_LOG

Instance domain identifier not defined in the PCP archive logA PCP client has requested information about an instance domain for one or more performance metrics, and there is no corresponding information in the set of PCP archives. If the client is using metric descriptors from the set of archives to identify the instance domain, this is less likely to happen.

Instance identifier not defined in the PCP archive logA PCP client has requested information about a specific instance of a performance metric, and there is no corresponding information in the set of PCP archives. If the client is using instance names from the instance domain in the set of archives (rather than hard-coded instance names) and instance identifiers from the results returned by pmFetch(3) or pmFetchArchive(3) this is less likely to happen.

Because instance domains may vary over time, clients may need to use the variant routines pmLookupInDomArchive(3) or pmNameInDomArchive(3) to manipulate the union of the instances in an instance domain over the life of an archive.

PM_ERR_LOGOVERLAP

Archives overlap in timeWhen using a context associated with a set of archives, the archives in the set may not overlap in time.

PM_ERR_LOGHOST

Archives differ by hostWhen using a context associated with a set of archives, the archives in the set must all have been generated on the same host.

PM_ERR_LOGTIMEZONE

Archives differ by time zoneWhen using a context associated with a set of archives, the archives in the set must all have been generated using the same time zone.

PM_ERR_LOGCHANGETYPE

The type of a metric differs among archivesWhen using a context associated with a set of archives, the type of each metric must be same in all of the archives.

PM_ERR_LOGCHANGESEM

The semantics of a metric differs among archivesWhen using a context associated with a set of archives, the semantics of each metric must be same in all of the archives.

PM_ERR_LOGCHANGEINDOM

The instance domain of a metric differs among archivesWhen using a context associated with a set of archives, the instance domain of each metric must be same in all of the archives.

PM_ERR_LOGCHANGEUNITS

The units of a metric differs among archivesWhen using a context associated with a set of archives, the units of each metric must be same in all of the archives.

These error codes are used in the interactions between pmcd(1) and the PMDAs that provide the performance data.

PM_ERR_PMDANOTREADY

PMDA is not yet ready to respond to requestsSome PMDAs have long initialization or reset times, and will respond to pmcd(1) with this error if they are busy at the moment. This error translates to PM_ERR_AGAIN for the PCP client who made the request to pmcd which caused the initial request to the PMDA. At some later time the PMDA will inform pmcd (see PM_ERR_PMDAREADY) that it is now ready to process requests, and client requests will begin to succeed.

PM_ERR_PMDAREADY

PMDA is now responsive to requestsUsed by PMDAs to asynchronously inform pmcd(1) that they are now willing to resume processing requests. See also PM_ERR_PMDANOTREADY.

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). Values for these variables may be obtained programmatically using the pmGetConfig(3) function.