PMLOADDERIVEDCONFIG(3)

💖 PMLOADDERIVEDCONFIG(3) 💖

okay so bestie, we're in the Library Functions Manual section today, and this one is literally the glow-up your metrics have been waiting for. it's pmLoadDerivedConfig and she is iconic. 🎀

---

✨ NAME ✨

pmLoadDerivedConfig — load derived metric definitions from files 🌸

---

🦋 C SYNOPSIS 🦋

#include <pcp/pmapi.h>

int pmLoadDerivedConfig(char *path);

cc ... -lpcp

---

💅 DESCRIPTION 💅

okay so picture this: derived metrics are how you take the metrics you already have and invent new ones on top of them, using cute little arithmetic expressions. and the definitions of those metrics? they can be persisted to disk and loaded back programmatically by monitor tools, which is exactly what pmLoadDerivedConfig does. no cap. ✨

The path parameter is a colon separated list of files and/or directories — yes, the syntax is the same as for the $PATH variable for sh(1) — and that's where the derived metric specifications get sourced from. 🌈

so how does a path turn into actual files? here's the vibe check:

• if a component is a file, that file is added to the list 📄
• else if a component is a directory, then recursive descent is used to enumerate all files below that directory, and those get added to the list 🗂️

Each file in the resulting list is parsed in order, following the derived metrics syntax described below. no skipping, no shortcuts, periodt.

---

🎀 what's inside the files 🎀

every line in the file(s) identified by path is one of three things:

1. a control line beginning with #control — see pmSetDerivedControl(3) for the deets
2. a comment line — otherwise, with a `#` in the first position of the line
3. the declaration of a derived performance metric, which is specified as:

• the name of the derived metric, using the same `dot notation` syntax that's used for PCP performance metrics — see PCPIntro(1) and PMNS(5) 👑
• an equals sign (`=`)
• a valid expression for a derived metric, as described in pmRegisterDerived(3)

for every line containing a derived metric definition, pmRegisterDerived(3) gets called to register the new derived metric. that's the whole assignment bestie, and she ate. 💅

---

🫶 giving your metric extra attributes 🫶

once a derived metric has been declared, it may be assigned additional attributes with a line of the form:

• the name of the derived metric
• a left parenthesis, an attribute type, and a right parenthesis
• an equals sign (`=`)
• an attribute value

Currently, attribute type may be either oneline or helptext, to designate the `one line` or expanded help text to be associated with the derived metric — see pmLookupText(3). 🧚

The attribute value may be either:

• arbitrary text following the `=` and ending at the end of the line, or
• a string enclosed in either single quotes (') or double quotes (")

in that second case, the attribute value may span multiple lines, and a simple escape mechanism is supported, namely: for any character `x`, `\x` is replaced by `x` — which is how you escape quotes inside a string, for example. 🙈 and there's a special case when the `\` comes at the end of the line, in which case the following newline is not included in the attribute value. sneaky but slay.

outside of attribute values, white space is ignored in the lines, and blank lines are ignored altogether. 💀

---

😭 the return value situation 😭

Because pmLoadDerivedConfig may process many files, each of which may contain many derived metric specifications, it is not possible to provide a specific error status on return. so instead: the result from pmLoadDerivedConfig will be the number of derived metrics successfully loaded from files on the given path. 🌟

Catastrophic errors — like not being able to open one of the files on the given path — will cause an immediate return with a negative return value that can be passed to pmErrStr(3) to obtain the associated error message. so like, if it's negative, something went very wrong, bestie. 🚨

When errors are encountered in the derived metric specifications, diagnostic messages are generated by pmRegisterDerived(3) and displayed via pmprintf(3). 📢

Also fyi: pmUnregisterDerived(3) may be used to undefine a derived metric by name, which removes all instances of the derived metric in all contexts, irrespective of how the derived metric was defined. she's thorough like that. 💅

---

🔥 EXAMPLE 🔥

# sample derived metric definitions
bad_in_pkts = network.interface.in.errors + network.interface.in.drops
# note the following would need to be on a single line ...
disk.dev.read_pct = 100 * delta(disk.dev.read) /
            (delta(disk.dev.read) + delta(disk.dev.write))
disk.dev.read_pct(oneline) = percentage of disk reads
disk.dev.read_pct(helptext) = '\
Percentage of disk reads compared to the total number of
disk reads and disk writes.'

# the operand metric (some.metric.bar) may not be defined
#control novalue=1
foo = some.metric.bar * hinv.ncpu

---

⭐ SEE ALSO ⭐

PCPIntro(1), sh(1), PMAPI(3), pmLookupText(3), pmRegisterDerived(3), pmSetDerivedControl(3), pmUnregisterDerived(3), pmprintf(3) and PMNS(5).

---

and that's the whole page bestie, you're officially a derived-metrics girlie now 🎀✨

this lil masterpiece comes to you courtesy of Performance Co-Pilot, and yeah, it's PMLOADDERIVEDCONFIG(3) — go forth and derive, ily 💖🦋👑