PMDALABEL(3)

💖 PMDALABEL(3) 💖

okay bestie, gather round, because this is a page from the Library Functions Manual and it's literally about filling up pmLabelSet structures with metric labels. yes, labels. the little name-tag stickers of the PCP world. 🎀

---

✨ NAME ✨

pmdaLabel, pmdaSetLabelCallBack — fill pmLabelSet structures with metric labels 🏷️✨

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>
#include <pcp/pmda.h>

int pmdaLabel(int ident, int type, pmLabelSet **sets, pmdaExt *pmda);
int pmdaSetLabelCallBack(pmdaInterface *dispatch,
                         pmdaLabelCallBack callback);

cc ... -lpcp_pmda -lpcp

do not forget the link flags bestie, -lpcp_pmda AND -lpcp, both of them, we are not doing half the job 💅

---

🦋 DESCRIPTION 🦋

so. part of the Performance Metrics Domain Agent (PMDA) API — that's the PMDA(3) thing, go read it — and pmdaLabel uses the standard PMDA(3) data structures to hand you back the labels for a performance domain, an instance domain, a metric, or individual instances, all in "JSONB" format, tucked into the sets data structure you passed in. no cap. 💖

the type argument is the main character here: it decides how to read ident AND what kind of label you're asking for. so, like:

• PM_LABEL_DOMAIN — when ident is a PMDA domain identifier 👑
• PM_LABEL_CLUSTER — when ident is a metric identifier and you're requesting labels for the cluster containing that metric 🗂️
• PM_LABEL_ITEM — when ident is a metric identifier ⭐
• PM_LABEL_INDOM — when ident is an instance domain identifier 🌈
• PM_LABEL_INSTANCES — when ident is a metric identifier and you want labels for all the instances of that metric 🫶

⚠️ the label sets pointer must be initialised to NULL before you call pmdaLabel, and space is only to be allocated when labels are actually present and returned. when that happens, the return code must indicate the number of label sets that got allocated. and heads up: this will only ever be greater than one in the PM_LABEL_INSTANCES case. one. literally just the one. except there. 😭

now, the tea ☕ — this is one of the few generic callbacks in libpcp_pmda (again: PMDA(3)) that is incomplete, meaning it needs a further pmdaLabelCallBack method of its own to actually work. you register that extra callback with pmdaSetLabelCallBack, and the pmdaLabelCallBack method has this prototype:

int func(pmInDom indom, unsigned int inst, pmLabelSet **set)

the whole purpose of the pmdaLabelCallBack routine is to return the label(s) for an individual instance inst of a given instance domain, indom. and its successful return code is significantly different from pmdaLabel's — like, do not mix these up — as described below 👇

---

💀 CAVEAT 💀

your PMDA has to be using PMDA_INTERFACE_7 or later, as specified in the call to pmdaDSO(3) or pmdaDaemon(3). older interface? it's giving not today. 🙈

---

🔥 DIAGNOSTICS 🔥

on success, pmdaLabel returns the number of label sets created. usually that's zero or one — except in the PM_LABEL_INSTANCES case, where more than one label set will often come back, one for each instance of the requested metric. so many little name tags. so many. 🎀🎀🎀

by contrast — and this is the plot twist — on success of the pmdaLabelCallBack routine you must return the number of labels successfully added to the provided labelset pointer, and not the total number of label sets. different number. different meaning. periodt. 💅

and if the labels for the requested entity could not be obtained because of a catastrophic failure — like an out of memory condition, that kind of nightmare — these routines will return a negative error code. 😭

---

👑 SEE ALSO 👑

pminfo(1), malloc(3), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pmdaInit(3) and pmLookupLabels(3). go read them, iykyk 🫶

---

and that's the whole page bestie!! this one came to you courtesy of Performance Co-Pilot, PCP, dated PMDALABEL(3) — slay, ate, no crumbs, go label some metrics 💖✨🦋