PMADDDERIVED(3)

💖 PMADDDERIVED(3) 💖

okay bestie, gather round, because this is the pmAddDerived / pmAddDerivedMetric situation and honestly? it's giving main character energy. this one lives in the Library Functions Manual section of the PCP crew, and it's all about registering a per-context derived metric name + definition. let's get into it 🫶

---

✨ NAME ✨

pmAddDerived, pmAddDerivedMetric — register a per-context derived metric name and definition

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

char *pmAddDerived(char *name, char *expr);
int pmAddDerivedMetric(char *name, char *expr, char **errmsg);

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

so derived metrics are literally the glow-up mechanic for the Performance Metrics Name Space (PMNS) — they let you add brand new metrics defined on the PCP client-side, built out of expressions over the performance metrics that already exist. iconic behavior tbh.

pmAddDerived and pmAddDerivedMetric are the routines you call to create per-context derived metrics. and no cap: you can only use them after the current PMAPI context has been created with pmNewContext(3). no context, no service. 💅

per-context derived metrics are similar in literally all aspects except scope to global derived metrics. the global ones are defined across all PMAPI contexts and get created with their associated besties pmRegisterDerived(3), pmRegisterDerivedMetric(3) and pmLoadDerivedConfig(3).

the arguments to pmAddDerived are name — the name of the new derived metric — and expr, which is the expression defining how the values of name should be computed.

pmAddDerivedMetric is the exact functional equivalent to pmAddDerived, except it hands you a simplified model of error handling where a formatted message comes back through the errmsg parameter. same energy, cuter error handling. 😌

for the complete description of the syntactic rules for name, the syntactic and semantic rules for expr, return values, the associated error reporting mechanisms, and the expression evaluation rules — go read the pmRegisterDerived(3) man page. it's the source of truth, fr fr.

okay so here's a genuinely important difference, don't skip it: for per-context derived metrics, all syntactic and semantic checks are performed at the time pmAddDerived or pmAddDerivedMetric is called. that's different to global derived metrics, where the semantic checks are delayed until the metric is used in a specific PMAPI context. so like, per-context checks everything up front, periodt.

once registered, a per-context derived metric persists for the life of the PMAPI context, but it gets destroyed as a side-effect of pmDestroyContext(3). rip to your derived metric, it had a good run. 🕊️

if you wanna undefine a derived metric by name, refer to pmUnregisterDerived(3) — and heads up, that one removes all instances of the derived metric in all contexts, irrespective of how the derived metric was defined. it does not care about your per-context boundaries, it's ruthless. 💀

---

🔥 DIAGNOSTICS 🔥

on success, pmAddDerived returns NULL. slay.

if a syntactic error is found at the time of calling, the value returned by pmAddDerived is a pointer into expr indicating where the error was found. to identify what the error actually was, your application should call pmDerivedErrStr(3) to retrieve the corresponding parser error message. teamwork, bestie. 🤝

pmAddDerivedMetric returns 0 and errmsg is undefined if the parsing is successful.

if the given expr does not conform to the required syntax, pmAddDerivedMetric returns -1 and a dynamically allocated error message string in errmsg. that error message is terminated with a newline and includes both the input name and expr, along with an indicator of the position at which the error was detected. e.g.

Error: pmAddDerivedMetric("my.disk.rates", ...) syntax error
4rat(disk.dev.read)
    ^

the position indicator line may be followed by an additional diagnostic line describing the nature of the error, when available.

in the case of an error, the caller is responsible for calling free(3) to release the space allocated for errmsg. don't forget. don't be that person. memory leaks are not a vibe. 🙈

---

👑 SEE ALSO 👑

PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3), pmLoadDerivedConfig(3), pmNewContext(3), pmRegisterDerived(3), pmRegisterDerivedMetric(3), pmUnregisterDerived(3) and PMNS(5).

---

and that's the whole page, bestie!! this one came to you straight from Performance Co-Pilot, the PMADDDERIVED(3) of it all 💖✨ go forth and derive responsibly, mwah 🎀🦋💅