PMAPI(3)

💖 PMAPI(3) — Library Functions Manual 💖

okay bestie, buckle UP, this is the intro to the Performance Metrics Application Programming Interface (that's PMAPI to its friends) 💅

---

✨ NAME ✨

PMAPI — introduction to the Performance Metrics Application Programming Interface

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

 ... assorted routines ...

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

so basically, inside the whole Performance Co-Pilot (aka PCP) universe, client applications get built using the Performance Metrics Application Programming Interface — the PMAPI — and that thing defines a procedural interface, with services that are literally tailor-made for apps that care a LOT about performance metrics. it's giving "made for this" energy 🎀

this description right here is the bird's-eye tour of the PMAPI and the context in which PMAPI applications run. the full deep dive lives in the Performance Co-Pilot Programmer's Guide, plus the manual pages for each individual PMAPI routine. iykyk 📚

---

🔥 PERFORMANCE METRICS — NAMES AND IDENTIFIERS 🔥

want the tea on the Performance Metrics Name Space (PMNS) and all the terms and concepts that come with it? go peek at PCPIntro(1) ✨

not every single PMID has to show up in every application's PMNS, no cap. for example, an app that monitors disk traffic will probably use a name space that references only the PMIDs for I/O statistics. very "stay in your lane, but make it metrics" 🫶

applications that use the PMAPI may each have their own independent versions of a PMNS, constructed from an initialization file when the app starts up — see pmLoadASCIINameSpace(3), pmLoadNameSpace(3), and PMNS(5) 🌈

internally (so, below the PMAPI), the implementation of the Performance Metrics Collection System (PMCS) uses only the PMIDs. a PMNS gives you an external mapping from a hierarchic taxonomy of names to PMIDs, which is super convenient in the context of a particular system or a particular use of the PMAPI. for the applications programmer, the routines pmLookupName(3) and pmNameID(3) translate between names in a PMNS and PMIDs, and vice versa 🔁 the PMNS may be traversed using pmGetChildren(3) and pmTraversePMNS. and the pmFetchGroup(3) functions combine metric name lookup, fetch, and conversion operations. iconic behavior honestly 👑

---

💅 PMAPI CONTEXT 💅

an application using the PMAPI may manipulate several concurrent contexts, and each one is associated with a source of performance metrics — like pmcd(1) on some host, or a set of archives of performance metrics as created by pmlogger(1) 📦

contexts get identified by a "handle" — a small integer value that's returned when the context is created. see pmNewContext(3) and pmDupContext(3). some PMAPI functions require an explicit "handle" to identify the correct context, but way more commonly the PMAPI function is executed in the "current" context. you can discover the current context with pmWhichContext(3) and change it with pmUseContext(3) 🔍

if a PMAPI context has not been explicitly established (or if the previous current context has been closed using pmDestroyContext(3)), then the current PMAPI context is undefined. not me leaving the context in the void 😭

besides the source of the performance metrics, the context also includes the instance profile and collection time (both described below), which control how much information is returned, and when that information was collected ⏰

---

🌟 INSTANCE DOMAINS 🌟

when performance metric values get returned across the PMAPI to a requesting application, there might be more than one value for a particular metric. multiple values — a.k.a. instances — for a single metric are typically the result of instrumentation being implemented for each instance of a set of similar components or services in a system. like independent counts for each CPU, or each process, or each disk, or each system call type, etc. 🍓 this multiplicity of values is not enumerated in the name space. instead, when performance metrics are delivered across the PMAPI by pmFetch(3), the format of the result accommodates values for one or more instances, with an instance-value pair encoding the metric value for a particular instance.

the instances are identified by an internal identifier assigned by the agent responsible for instantiating the values for the associated performance metric. each instance identifier has a corresponding external instance identifier name (an ASCII string). the routines pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(3) may be used to enumerate all instance identifiers, and to translate between internal and external instance identifiers 🔄

all of the instance identifiers for a particular performance metric are collectively known as an instance domain. multiple performance metrics may share the same instance domain. sharing is caring 💞

if only one instance is ever available for a particular performance metric, the instance identifier in the result from pmFetch(3) assumes the special value PM_IN_NULL and may be ignored by the application, and only one instance-value pair appears in the result for that metric. under these circumstances, the associated instance domain (as returned via pmLookupDesc(3)) is set to PM_INDOM_NULL to indicate that values for this metric are singular ✨

now, the difficult issue of transient performance metrics (per-filesystem information, hot-plug replaceable hardware modules, etc.) means that repeated requests for the same PMID may return different numbers of values, and/or some changes in the particular instance identifiers returned 😳 which means applications need to be aware that metric instantiation is guaranteed to be valid at the time of collection only. similar rules apply to the transient semantics of the associated metric values. in general though, it's expected that the bulk of the performance metrics will have instantiation semantics that are fixed over the execution life-time of any PMAPI client 🧚

---

👑 THE TYPE OF METRIC VALUES 👑

the PMAPI supports a wide range of format and type encodings for the values of performance metrics, namely signed and unsigned integers, floating point numbers, 32-bit and 64-bit encodings of all of the above, ASCII strings (C-style, NULL byte terminated), and arbitrary aggregates of binary data. the range? unmatched 💯

the type field in the pmDesc structure returned by pmLookupDesc(3) identifies the format and type of the values for a particular performance metric within a particular PMAPI context 🔬

note that the encoding of values for a particular performance metric may be different for different PMAPI contexts, because of differences in the underlying implementation for different contexts. however it's expected that the vast majority of performance metrics will have consistent value encoding across all versions of all implementations, and hence across all PMAPI contexts 🤝

the PMAPI supports routines to automate the handling of the various value formats and types — especially for the common case where conversion to a canonical format is desired. see pmExtractValue(3) and pmPrintValue(3) ✨

---

🎀 THE DIMENSIONALITY AND SCALE OF METRIC VALUES 🎀

independent of how the value is encoded, the value for a performance metric is assumed to be drawn from a set of values that can be described in terms of their dimensionality and scale by a compact encoding, like this 👇 the dimensionality is defined by a power, or index, in each of 3 orthogonal dimensions, namely Space, Time and Count (or Events, which are dimensionless). for example I/O throughput might be represented as Space/Time, while the running total of system calls is Count, memory allocation is Space, and average service time is Time/Count. in each dimension there are a number of common scale values that may be used to better encode ranges that might otherwise exhaust the precision of a 32-bit value 📐

orthogonally, extra "units" information is also supported for values that represent physical and electrical measurements — temperature, voltage, current, power, etc. ⚡

this information is encoded in the pmUnits structure, which is embedded in the pmDesc structure returned from pmLookupDesc(3) 💫

the routine pmConvScale(3) is provided to convert values in conjunction with the pmUnits structures that define the dimensionality and scale of the values for a particular performance metric as returned from pmFetch(3), and the desired dimensionality and scale of the value the PMAPI client wishes to manipulate. alternatively, the pmFetchGroup(3) functions can perform data format and unit conversion operations, specified by textual descriptions of desired unit / scales 🔁

---

🌸 INSTANCE PROFILE 🌸

the set of instances for performance metrics returned from a pmFetch(3) call may be filtered or restricted using an instance profile. there is one instance profile for each PMAPI context the application creates, and each instance profile may include instances from one or more instance domains 🎯

the routines pmAddProfile(3) and pmDelProfile(3) may be used to dynamically adjust the instance profile 🛠️

---

⏰ COLLECTION TIME ⏰

for each set of values for performance metrics returned via pmFetch(3), there's an associated "timestamp" that serves to identify when the performance metric values were collected. for metrics being delivered from a real-time source (i.e. pmcd(1) on some host) this would typically be not long before they were exported across the PMAPI, and for metrics being delivered from a set of archives, this would be the time when the metrics were written into the archive 📼

there's an issue here of exactly when individual metrics may have been collected — especially given their origin in potentially different Performance Metric Domains, plus variability in the metric updating frequency at the lowest level of the Performance Metric Domain. the PMCS opts for the pragmatic approach, in which the PMAPI implementation undertakes to return all of the metrics with values accurate as of the timestamp, to the best of our ability. the belief is that the inaccuracy this introduces is small, and the additional burden of accurate individual timestamping for each returned metric value is neither warranted nor practical (from an implementation viewpoint) 🫠

of course, in the case of collection of metrics from multiple hosts, the PMAPI client must assume the sanity of the timestamps is constrained by the extent to which clock synchronization protocols are implemented across the network 🌐

a PMAPI application may call pmSetMode(3) to vary the requested collection time — e.g. to rescan performance metrics values from the recent past, or to "fast-forward" through a set of archives ⏩

---

✨ GENERAL ISSUES OF PMAPI PROGRAMMING STYLE ✨

Okay so bestie, before we dive into the chaos, let's talk about how PMAPI handles lists and memory, because it's lowkey iconic but also highkey important. 💅

Across the whole PMAPI, whenever you see arguments or results that involve a "list of something", they're declared as arrays with an associated argument or function value that tells you how many elements are in the list. Why? To avoid the whole varargs(3) mess and sentinel-terminated lists. Periodt. ✨

When the size of a result is known at the time of the call, it's your job (the caller's) to allocate — and possibly free — the storage, and the called function will just assume the result argument is the right size. No cap. 🫶

But when the result is variable size and that size cannot be known in advance (think pmGetChildren(3), pmGetInDom(3), pmNameInDom(3), pmNameID(3), pmLookupLabels(3), pmLookupText(3) and pmFetch(3)), the PMAPI implementation uses a range of dynamic allocation schemes inside the called routine. And guess what? You're responsible for releasing that storage when you don't need it anymore. 💀

In some cases that's just a simple free(3) call, but in others — most notably for the result from pmFetch(3) — you should use special routines like pmFreeResult(3) and pmFreeLabelSets(3) to release the storage. Don't skip this, bestie. 🙈

As a general rule: if the called routine returns an error status, then no allocation will have been done, and any pointer to a variable sized result is undefined. So don't go touching it. 🚫

---

🩺 DIAGNOSTICS 🩺

Where error conditions may arise, the functions that make up the PMAPI all follow one single, simple error notification scheme. It's giving consistency. ✨

• The function returns an integer.
• Values >= 0 indicate no error, and maybe some positive status, like the number of things actually processed. Slay. 💖
• Values < 0 indicate an error, with a global table of error conditions and error messages.

The PMAPI routine pmErrStr(3) translates error conditions into error messages. By convention, the small negative values are assumed to be negated versions of the Unix error codes as defined in <errno.h>, and the strings returned are as per strerror(3). The larger, negative error codes are PMAPI error conditions. 👑

One error that's common to all PMAPI routines that interact with pmcd(1) on some host is PM_ERR_IPC, which indicates the communication link to pmcd(1) has been lost. So if you see that, the vibe is off and the connection is gone. 😭

---

🧵 MULTI-THREADED APPLICATIONS 🧵

The original design for PCP was based around single-threaded applications — or more strictly, applications where only one thread was ever expected to call the PCP libraries. But bestie, this restriction has been relaxed for libpcp to allow the most common PMAPI routines to be safely called from any thread in a multi-threaded application. We love to see it. 🦋

However, the following groups of functions and services in libpcp are still restricted to being called from a single thread. And this is enforced by returning PM_ERR_THREAD when an attempt to call the routines in each group from more than one thread is detected. Not me being dramatic, it's just facts. 💅

1. Any use of a PM_CONTEXT_LOCAL context, as the DSO PMDAs that are called directly from libpcp may not be thread-safe. So keep that one on a single thread, okay? 🙏

---

🌍 PCP ENVIRONMENT 🌍

Most environment variables are described in PCPIntro(1). In addition, 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). And you can get values for these variables programmatically using the pmGetConfig(3) function. Iconic. ⭐

---

👀 SEE ALSO 👀

PCPIntro(1), PCPIntro(3), PMDA(3), PMWEBAPI(3), pmGetConfig(3), pcp.conf(5), pcp.env(5) and PMNS(5).

---

And that's a wrap, bestie! This page came to you from Performance Co-Pilot, version PCP, and it's the PMAPI(3) manual page. Stay slaying those performance metrics. 💖✨🎀