PMSETMODE(3)

💖 PMSETMODE(3) 💖

okay bestie, welcome to pmSetMode from the Library Functions Manual ✨ this is the PCP girlie that sets your collection time AND your mode for the current PMAPI context, and honestly? she's a baddie 🫶

---

🌸 NAME 🌸

pmSetMode — set collection time and mode parameters for the current PMAPI context 💅

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

int pmSetMode(int mode, const struct timespec *when,
              const struct timespec *delta);

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

so pmSetMode is what you call to define the collection time and/or the mode for accessing performance metrics and metadata in the current Performance Metrics Application Programming Interface (PMAPI) context. no cap.

this mode is lowkey powerful because it changes the semantics of every subsequent call to these PMAPI routines: pmFetch(3), pmFetchArchive(3), pmLookupDesc(3), pmGetInDom(3), pmLookupInDom(3), pmLookupLabels(3) and pmNameInDom(3). like, the whole vibe shifts, periodt.

it's intended mainly for retrospective analysis of performance metrics from a PCP archive, and the options below let an application implement seeking to an arbitrary time within the archive, playback, fast forward, reverse, etc. — all by alternating calls to pmSetMode and pmFetch(3). it's giving time travel tbh 🕰️

if mode is PM_MODE_LIVE then all information is returned from the active pool of performance metrics as of the time that the PMAPI call is made, and the other two parameters to pmSetMode (when and delta) are ignored 🙈. PM_MODE_LIVE is the default mode when a new PMAPI context is created with type PM_CONTEXT_HOST (i.e. fetching metrics from pmcd(1)) or PM_CONTEXT_LOCAL, and this mode is rarely used in calls to pmSetMode.

the other values of mode are used with PCP archives, where the associated PMAPI context must be of type PM_CONTEXT_ARCHIVE (when it was created with pmNewContext(3)), and the when parameter defines the current time within the archive. every request for metric values and metadata (metric descriptions and instance identifiers from the instance domains) gets processed to reflect the state in the archive as of the current time. iconic 💫

when you're picking a value for when, bestie: the time at the start of the archive can be established from the ll_start field in the structure returned from a call to pmGetArchiveLabel(3) or the start field in the structure returned from a call to pmGetArchiveLabel(3), and the time at the end of the archive can be established by calling pmGetArchiveEnd(3).

and as a special case 👀 — if when is NULL then the mode and delta arguments are used as described below, but the current time in the archive is not altered.

---

⏰ TIME-DRIVEN ARCHIVE MODE ⏰

if mode is PM_MODE_INTERP then as metric values are retrieved from the archive with pmFetch(3) the current time is returned as the timestamp in the pmResult structure and the current time moves on 🚶‍♀️; if delta is positive, the current time moves forwards, else the current time moves backwards. and the adjustment to the current time is applied even if the pmFetch(3) fails to return values for any metrics or returns an error, e.g. PM_ERR_EOL because the current time is outside the range defined by the records in the archive. she keeps it moving no matter what 💀

when metric values are being requested via pmFetch(3) the current time may not exactly match the times at which values have been recorded in the archive, so the returned metric values are computed from the observed metric values in the archive (usually at times close to the current time).

for metrics with semantics of PM_SEM_COUNTER, the computed value is based on linear interpolation between the last observation before the current time and the first observation after the current time 📈.

for metrics with semantics of PM_SEM_INSTANT or PM_SEM_DISCRETE, the computed value is based on values in the neighbourhood of the current time.

the algorithms used in these computations depend on the semantics of the metrics and the time series of observed values in the archive; a fuller explanation may be found in the white paper Explaining Value Interpolation with PCP Archives found at https://pcp.io/papers/archive-interpolation.pdf 📄✨

---

📼 RECORD-DRIVEN ARCHIVE MODES 📼

if mode is PM_MODE_FORW or PM_MODE_BACK then when metric values are being requested via pmFetch(3) the archive will be scanned in a forwards (PM_MODE_FORW) or backwards (PM_MODE_BACK) direction in time, until an archive record is encountered with values for at least one of the requested metrics. this archive record is used to provide as many of the requested metrics as possible, and these are returned with the timestamp if the record in the archive, which becomes the new current time. slay 🎀

⚠️ note that any metrics requested via pmFetch(3) that do not have a value in the archive record at the new current time will return no values, so this mode is most useful for archives where all of the metrics of interest have been logged regularly at the same time in the archive. otherwise, each pmFetch(3) will contain only the subset of the requested metrics and any associated instances found in the qualifying archive record.

the delta parameter is ignored 🙅‍♀️, because the current time is driven by the timestamp in the matching archive record. so there is no concept of stepping through the archive in regular time with this mode, although if the requested metrics appear at regular intervals in the archive the current time may advance by regular intervals — but this is serendipitous ✨

if no qualifying metrics can be found in the requested direction of searching before the end or start of the archive is encountered, then pmFetch(3) returns the special error indicator, PM_ERR_EOL. 😭

---

👑 RECOMMENDATIONS 👑

when processing PCP archives, PM_MODE_INTERP is preferred because:

• this maximizes the information that will be returned in each pmFetch(3) 💖
• this returns values at regular intervals of the current time, independent of the logging frequency for requested metrics in the archive 🕐
• this works with any PCP archive, as opposed to the record-driven modes which may work acceptably for archives with regular logging of all requested metrics, but may fail to report complete or useful results for other archives 🫶
• this mode provides the closest semantic match to PM_MODE_LIVE and leads to the least user surprise when moving between real-time monitoring and retrospective analysis 🌈

---

🧚 EXAMPLES 🧚

to replay interpolated metrics from an archive at 10 second intervals, the following code fragment could be used:

struct timeval mytime;
int mydelta = 10 * 1000;      /* msec */
pmLogLabel label;
pmResult result;

pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveLabel(&label);
mytime = label.ll_start;
pmSetMode(PM_MODE_INTERP, &mytime, mydelta)

while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
    /*
     * process interpolated metric values as of
     * result->timestamp
     */
    . . .
    pmFreeResult(result);
}

the following code fragment may be used to dump values for selected metrics in an archive in reverse temporal sequence 🔄:

struct timespec mytime;
pmResult result;

pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
pmGetArchiveEnd(&mytime);
pmSetMode(PM_MODE_BACK, &mytime, NULL);

while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
    /*
     * process logged metric values as of result->timestamp
     */
    . . .
    pmFreeResult(result);
}

---

💀 COMPATIBILITY 💀

prior to PCP 7.0 the when argument was a struct timeval and the delta argument was an int (in units of milliseconds). to support PMAPI transition, the old interface and semantics can be used if applications are recompiled with -DPMAPI_VERSION=2. throwback fr fr 🕰️

for a time in PCP 6.x there was a routine with the same semantics as the current pmSetMode called pmSetModeHighRes — although this is now deprecated and compile-time support for pmSetModeHighRes will be removed in a future release. so don't get attached bestie 💔

---

🩺 DIAGNOSTICS 🩺

• PM_ERR_MODE — the mode parameter is invalid 🚫

---

🔗 SEE ALSO 🔗

pmcd(1), PMAPI(3), pmFetch(3), pmFetchArchive(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmGetInDom(3), pmLookupDesc(3), pmLookupInDom(3), pmLookupLabels(3), pmNameInDom(3) and pmNewContext(3).

---

okay that's the whole page bestie, and the Performance Co-Pilot girlies over at PCP made it — so when you see PMSETMODE(3) floating around your terminal, that's this exact manual page. go read your archives, interpolate responsibly, and stan PM_MODE_INTERP 💅✨🎀