PMDERIVEDCONTROL(3)

✨ PMDERIVEDCONTROL(3) ✨

okay bestie, this one lives in the Library Functions Manual section of the PCP docs and it's literally the remote control for derived metrics 💅 no cap.

---

🌸 NAME 🌸

pmGetDerivedControl, pmSetDerivedControl — get and set controls for derived metrics. yes, the name is doing exactly what it says on the tin, we love a transparent icon 🫶

---

🎀 C SYNOPSIS 🎀

#include <pcp/pmapi.h>

int pmGetDerivedControl(int what, int *valuep);
int pmSetDerivedControl(int what, int value);

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

So these routines are your little knobs-and-dials situation for the derived metric services 🎛️ — specifically the ones that get activated for global derived metrics via pmRegisterDerived(3), pmRegisterDerivedMetric(3) and pmLoadDerivedConfig(3), or for per-context derived metrics via pmAddDerived(3) and pmAddDerivedMetric(3).

The what argument picks which control or option you're talking about, the value argument is what you hand to pmSetDerivedControl, and the valuep argument is where pmGetDerivedControl drops the answer back for you 💖

what has to be one of these, no substitutions:

• PCP_DERIVED_GLOBAL_LIMIT — the max number of global derived metrics that may be defined. the value should be greater than zero, or -1 (which means no limit, live your truth). the initial value is -1.
• PCP_DERIVED_CONTEXT_LIMIT — the max number of per-context derived metrics that may be defined. the value should be greater than zero, or -1 (again: no limit). the initial value is -1.
• PCP_DERIVED_DEBUG_SYNTAX — debug diagnostics during parsing of the derived metric expression. value 1 turns the diagnostics on, 0 turns them off. the initial value is 0.
• PCP_DERIVED_DEBUG_SEMANTICS — debug diagnostics for semantic checks during the binding of metrics in the derived metric expression to the available metrics in a new PMAPI context. value 1 enables the diagnostics, 0 disables them. the initial value is 0.
• PCP_DERIVED_DEBUG_EVAL — debug diagnostics when derived metrics get used in PMAPI operations like pmFetch(3), pmGetChildren(3), pmGetChildrenStatus(3), pmLookupDesc(3), pmLookupName(3), pmNameAll(3), pmNameID(3) and pmTraversePMNS(3). value 1 enables the diagnostics, 0 disables them. the initial value is 0.
• PCP_DERIVED_OPTION_NOVALUE — okay so when a performance metric (one being used as an operand inside a derived metric expression) is not available — think missing from a PCP archive context, or not provided by any PMDA for a host context — the default behaviour is to mark the derived metric as undefined. but if you set this option to 1 (default is 0), then any metric that isn't available gets mapped to the novalue() constructor instead (peep pmRegisterDerived(3) for the details). which basically means the metric is defined, but attempts to retrieve values via pmFetch(3) will return PM_ERR_VALUE (Missing metric value(s)). it's giving "technically present, emotionally unavailable" 😭

---

👑 RETURN VALUES 👑

Both routines return 0 on success. otherwise you get a value less than 0, and you can decode it with pmErrStr(3).

There's some overloading of error codes going on here, needed to accommodate the unusual semantics of these routines — described below, bestie, don't shoot the messenger 🙈

• PM_ERR_NAME — what is not one of the expected values.
• PM_ERR_ARG — the value provided to pmSetDerivedControl is not within the acceptable range.
• PM_ERR_NOCONTEXT — getting or setting PCP_DERIVED_CONTEXT_LIMIT only makes sense when there is a current PMAPI context.
• PM_ERR_AGAIN — the pmSetDerivedControl request would violate precedence rules (see below, they're coming, stay with me).

---

🌈 OTHER OPTIONS 🌈

All of the controls and options that pmSetDerivedControl exposes can also be set in two other ways. two!! choices!! main character energy fr fr ⭐

1. Setting the PCP_DERIVED_CONTROL environment variable to a value of the form name=integer, where name is one of the what macros described above, stripped of the PCP_DERIVED_ prefix — e.g. novalue=1. name is case insensitive and multiple specifications are allowed, separated by commas. No whitespace is allowed. (whitespace is not the vibe, apparently 💀)
2. Use of a #control line in a derived metric configuration file, where the text following the #control follows exactly the same rules as for the PCP_DERIVED_CONTROL environment variable described above. iconic, consistent, we stan.

So given these options can be specified in multiple ways, possibly with different values, here are the precedence rules: if PCP_DERIVED_CONTROL is set, then that value is honoured. else, the most recently set value from #control or pmSetDerivedControl is used. periodt. 🔥

---

💜 SEE ALSO 💜

PCPIntro(1), pmAddDerived(3), pmAddDerivedMetric(3), PMAPI(3), pmErrStr(3), pmLoadDerivedConfig(3), pmRegisterDerived(3), pmRegisterDerivedMetric(3) and PMNS(5).

---

and that's the whole page bestie, no crumbs left 🍓 this one's from Performance Co-Pilot, page PMDERIVEDCONTROL(3) — go forth and control your derived metrics responsibly, mwah 💖✨