PCPINTRO(3)

📦
version 7.2.2 · 3 versions
, in arch rolling, centos-stream 10, centos-stream 9, debian trixie, fedora 43, fedora 44, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 PCPIntro 💖 — your bestie's guide to the PCP libraries

PCPINTRO(3) · Library Functions Manual · ✨ part 1 of 2, so don't go anywhere ✨

✨ NAME ✨

PCPIntro — the intro to the Performance Co-Pilot (PCP) libraries 🦋

🎀 INTRODUCTION 🎀

okay so. Performance Co-Pilot (PCP) is a toolkit designed for monitoring and managing system-level performance. it's giving observability but as a whole ecosystem 💅

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 — one per routine, no cap, they each get their own moment ✨

Most routines return an integer value; greater than or 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.

💀 GENERAL ERRORS 💀

These common errors may occur in various PCP interactions. buckle up, there's a lot of them, but honestly they're all iconic in their own way 😭

PM_ERR_TIMEOUT

Timeout waiting for a response from PMCD

Many 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 application

Some 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. like, the metric's just not there for you bestie 🙈

PM_ERR_IPC

IPC protocol failure

Generic protocol failure on a pipe or socket connecting two PCP applications, e.g. client-pmcd, or client-pmtime, or PMDA-pmcd or pmlc-pmlogger. the connection is lowkey not connecting 💀

PM_ERR_TEXT

One-line or help text is not available

Set 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, e.g.

  1. Bad value for the metric pmcd.timezone when trying to set the timezone via pmNewContextZone(3) for a remote or archive context.
  2. Attempting to interpolate values for a metric with non-numeric data type from a set of PCP archives.
  3. A bad result data structure passed to pmStore(3).

PM_ERR_NAME

Unknown metric name

Just what the message says. fr fr, that's the whole thing 💅

PM_ERR_PMID

Unknown or illegal metric identifier

Just what the message says.

PM_ERR_INDOM

Unknown or illegal instance domain identifier

A request nominates an instance domain that is unknown or PM_INDOM_NULL. May occur as a consequence of the instance domain identifier passed by a PCP client to pmGetInDom(3), pmLookupInDom(3), pmNameInDom(3), pmGetInDomArchive(3), pmLookupInDomArchive(3), pmNameInDomArchive(3) or a request passed from pmcd(1) to a PMDA.

PM_ERR_EOF

IPC channel closed

End of file on a pipe or socket connecting two PCP applications, e.g. client-pmcd, or client-pmtime or PMDA-pmcd.

PM_ERR_NOCONTEXT

Attempt to use an illegal context

Typically caused by a PCP client that tries to make calls before calling pmNewContext(3) or after calling pmDestroyContext(3). bestie you forgot to set up first 😭

PM_ERR_PERMISSION

No permission to perform requested operation

PCP-specific access controls apply to pmcd(1) and pmlogger(1). Platform-specific permission errors are returned as -EPERM.

PM_ERR_CONV

Impossible value or scale conversion

Some value conversion requests are illegal, e.g. bad debug flag symbolic name for -D/--debug option, or asking pmExtractValue(3) to translate non-numeric data types to numbers and vice versa.

PM_ERR_TRUNC

Truncation in value conversion

Some 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 unsigned

Some 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 type

The 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 specification

Some 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) required

Some 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/--fetchall option to pminfo(1).

PM_ERR_INST

Unknown or illegal instance identifier

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

PM_ERR_MODE

Illegal mode specification

Illegal mode argument to pmSetMode(3).

PM_ERR_PROFILESPEC

NULL pmInDom with non-NULL instlist

Bad arguments passed from a PCP client to pmAddProfile(3).

PM_ERR_TOOSMALL

Insufficient elements in list

Parameter passing error by caller specifying a list with less than one element to pmFetch(3), pmLookupName(3) or pmStore(3).

PM_ERR_FAULT

QA fault injected

For testing, there is a ``fault injection'' version of libpcp and this error indicates a misuse of the fault injection infrastructure.

PM_ERR_THREAD

Operation not supported for multi-threaded applications

As documented in PMAPI(3) and elsewhere, some libpcp routines are intended solely for use from single-threaded applications. no threading for those ones, sorry bestie 🫶

PM_ERR_NOCONTAINER

Container not found

The user supplied container name does not match any known container.

PM_ERR_BADSTORE

Bad input to pmstore

The metric value provided for a pmStore(3) operation is in the wrong format, or of the wrong type or has the wrong number of values.

PM_ERR_TOOBIG

Result size exceeded

Indicates 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 change

Not 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 injected

Used only for PCP Quality Assurance (QA) testing.

PM_ERR_NYI

Functionality not yet implemented

Self explanatory and rarely used. it's giving "coming soon" energy 🎀

PM_ERR_GENERIC

Generic error, already reported above

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

PM_ERR_BADDERIVE

Derived metric definition failed

When registering a derived metric, the metric expression is either syntactically or semantically incorrect.

PM_ERR_NOLABELS

No support for metric label metadata

Operation requires metric labels, but none are available.

🦋 CLIENT-PMCD ERRORS 🦋

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 request

A 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 exceeded

The 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 available

Used 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 botch

Internal error in the communication between a client application and pmcd(1) - should not occur.

PM_ERR_NEEDCLIENTCERT

PMCD requires a client certificate

Authentication failure.

PM_ERR_PMDAFENCED

PMDA is currently fenced and unable to respond to requests

A privileged user has decided to isolate a PMDA from pmcd(1) using a pmStore(1) operation on the pmcd.agent.fenced metric, which means all fetch-level requests to that PMDA are being blocked.

💾 CLIENT-ARCHIVE ERRORS 💾

okay bestie, these ones pop off when a PCP client is chatting with the library routines that serve up historical performance data from PCP archives made by pmlogger(1). archive lore, iykyk 🗂️✨

PM_ERR_LOGFILE — Missing archive file 🫥

so every PCP archive is actually multiple physical files, exactly like pmlogger(1) explains. you get this error when one of those physical files is just… gone, or can't be opened for reading. not me losing a whole file 💀

PM_ERR_EOL — End of PCP archive 🏁

you tried to read past the end file of the last volume in a set of PCP archives, <em>or</em> past the end of the time window (that's the one you set with a -T/--finish option) for a set of PCP archives. that's it, that's the whole archive, no more girlies left to read 🌸

PM_ERR_NOTHOST — Operation requires context with host source of metrics 🖥️

calls to pmStore(3) require a host context and are simply not supported for PCP archives, periodt.

also, for archives created with versions of PCP prior to 4.0, the pmLookupText(3) and pmLookupInDomText(3) calls will return this code for archive PMAPI contexts — because help and one-line text was not previously recorded in archives. the vibes were minimal back then, lowkey 🙈

PM_ERR_LOGREC — Corrupted record in a PCP archive 💔

PCP archives can become corrupted for a variety of reasons, but the most common one is pmlogger(1) getting terminated prematurely without flushing its output buffers. rude of it honestly.

PM_ERR_LABEL — Illegal label record at start of a PCP archive file 🏷️

each physical file in a PCP archive should begin with a common label record. this is a special case of the PM_ERR_LOGREC errors.

PM_ERR_NODATA — Empty archive file 🕳️

an empty physical file can never be part of a valid PCP archive — at bare minimum the label record should be present. this is a special case of the PM_ERR_LOGREC errors.

PM_ERR_NOTARCHIVE — Operation requires context with archive source of metrics 📦

this hits when you call one of the archive variant routines — i.e. pmFetchArchive(3), pmGetInDomArchive(3), pmLookupInDomArchive(3) or pmNameInDomArchive(3) — while the current context isn't associated with a set of PCP archives. wrong context, bestie 💅

PM_ERR_PMID_LOG — Metric not defined in the PCP archive 🔍

a PCP client asked for info about a metric and there's just no corresponding information in the set of PCP archives. ngl this should not happen for well-behaved PCP clients — so if you're seeing it, the client is not being well-behaved 😭

PM_ERR_INDOM_LOG — Instance domain identifier not defined in the PCP archive 🗂️

a PCP client asked for info about an instance domain for one or more performance metrics, and there's 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. 🫶

and listen — because instance domains may vary over time, clients may need to use the variant routines pmGetInDomArchive(3) or pmLookupInDomArchive(3) or pmNameInDomArchive(3) to manipulate the union of the instances in an instance domain over the life of an archive. time is real, the domain shifts, deal with it 💫

PM_ERR_INST_LOG — Instance identifier not defined in the PCP archive 🧩

a PCP client asked for info about a specific instance of a performance metric, and there's 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) <em>and</em> instance identifiers from the results returned by pmFetch(3) or pmFetchArchive(3), this is less likely to happen. doing it the right way really does eat 💅

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 time ⏰

when you're using a context associated with a set of archives, the archives in that set may not overlap in time. no double-dipping in the timeline, bestie.

PM_ERR_LOGHOST — Archives differ by host 🌐

when you're using a context associated with a set of archives, every archive in the set must all have been generated on the same host. one host only, we don't mix 🚫

PM_ERR_LOGCHANGETYPE — The type of a metric differs among archives 🎭

when you're 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 archives 🧠

when you're 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 archives 🌀

when you're 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 archives 📏

when you're using a context associated with a set of archives, the units of each metric must be same in all of the archives.

⏱️ TIME CONTROL ERRORS ⏱️

these ones show up in the interactions between a GUI PCP client and the time control services provided by pmtime(1). it's giving… scheduling drama 🎀

PM_ERR_ISCONN — Already Connected 🔌

a PCP client application called pmTimeConnect(3) while already connected to a pmtime(1) instance. bestie you're already in the group chat.

PM_ERR_NOTCONN — Not Connected 📴

a PCP client application called one of the time control routines pmTime*(3) when not currently connected to any pmtime(1) instance. no connection, no service 🙈

PM_ERR_NEEDPORT — A non-null port name is required 🚪

if a shared pmtime(1) instance is being created, the port argument to pmTimeConnect(3) must not be invalid.

🌈 NAMESPACE ERRORS 🌈

these can pop up in the processing of PCP namespace operations. a PCP namespace, see PMNS(5), provides the external names and the internal identifiers for the available performance metrics. it's the whole name-to-id pipeline, iconic honestly ✨

PM_ERR_NONLEAF — Metric name is not a leaf in PMNS 🍃

the metric name passed to pmLookupName(3) names a non-terminal path in the namespace — i.e. a group of metrics rather than a single metric. you asked for the whole tree, not the leaf 🥲

PM_ERR_DUPPMNS — Attempt to reload the PMNS 🔁

when you're using an explicit local namespace, it is illegal to call either of pmLoadNameSpace(3) or pmLoadASCIINameSpace(3) more than once.

PM_ERR_PMNS — Problems parsing PMNS definitions 🧾

only occurs when an ASCII namespace is explicitly loaded.

PM_ERR_NOPMNS — PMNS not accessible 🚫

only occurs when an ASCII namespace is explicitly loaded.

🔥 PMCD-PMDA ERRORS 🔥

these error codes are used in the interactions between pmcd(1) and the PMDAs that provide the performance data. the backstage collab we didn't know we needed 💖

PM_ERR_PMDANOTREADY — PMDA is not yet ready to respond to requests 🥱

some PMDAs have long initialization or reset times, and they'll respond to pmcd(1) with this error if they're 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. it's not a no, it's a not right now 🫶

PM_ERR_PMDAREADY — PMDA is now responsive to requests ✅

used by PMDAs to asynchronously inform pmcd(1) that they are now willing to resume processing requests. see also PM_ERR_PMDANOTREADY. the glow-up arc, we love to see it 👑

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

bestie this is the config lore right here — know your env vars and you know everything 💜

👀 SEE ALSO 👀

PCPIntro(1), pmcd(1), pmerr(1), pminfo(1), pmtime(1), pmstore(1), pmlogger(1), PMAPI(3), pmAddProfile(3), pmDelProfile(3), pmConvScale(3), pmNewContext(3), pmDestroyContext(3), pmErrStr(3), pmExtractValue(3), pmFetch(3), pmFetchArchive(3), pmGetConfig(3), pmGetInDom(3), pmGetInDomArchive(3), pmLoadNameSpace(3), pmLookupInDom(3), pmLookupInDomText(3), pmLookupName(3), pmLookupText(3), pmNameInDom(3), pmNameInDomArchive(3), pmSetMode(3), pmStore(3), pmTimeConnect(3), pcp.conf(5), pcp.env(5) and PMNS(5).

and that's a wrap on PCPINTRO(3) bestie!! 🎀 this one ships out from the Performance Co-Pilot crew, tagged with the version string PCP and stamped with its date, and it's literally all yours to keep. go forth and debug, you absolute icon 💅✨🦋

📦 where this page comes from