PMIADDMETRIC(3)

💖 PMIADDMETRIC 💖

okay bestie, so you know the pmiAddMetric function from the Performance Co-Pilot library? yeah, that one. it lives in the Library Functions Manual and honestly? it's giving main character energy for the whole LOGIMPORT era. let's get into it 🫶

---

✨ NAME ✨

pmiAddMetric — add a new metric definition to a LOGIMPORT context. periodt, that's the whole job.

---

🌸 C SYNOPSIS 🌸

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

int pmiAddMetric(const char *name, pmID pmid, int type, pmInDom indom,
                 int sem, pmUnits units);

cc ... -lpcp_import -lpcp

🎀 Perl SYNOPSIS 🎀

use PCP::LogImport;

pmiAddMetric($name, $pmid, $type, $indom, $sem, $units);

🦋 Python SYNOPSIS 🦋

from pcp import pmi

log.pmiAddMetric(name, pmid, type, indom, sem, units)

---

💅 DESCRIPTION 💅

so basically, as part of the Performance Co-Pilot Log Import API (go read LOGIMPORT(3) if you haven't, it's the whole vibe), pmiAddMetric is the function you call to define a brand new metric. like, manifesting a metric into existence ✨

the metric's name has to follow the naming conventions described in PCPIntro(1), and it should be unique for each LOGIMPORT context. yes, should. no cap.

the other arguments are, in effect, the fields of a pmDesc structure. if you want the full tea on the values and semantics of every component in that structure — and therefore which argument values are actually valid for pmiAddMetric — go look at pmLookupDesc(3). she's the source of truth, fr fr.

the internal identifier for the metric can be given using the pmid argument, and it must be unique for each LOGIMPORT context. the value for pmid would typically be constructed using the pmID_build macro, e.g. pmID_build(PMI_DOMAIN, 0, 3) for the fourth metric in the first "cluster" of metrics in the Performance Metrics Domain PMI_DOMAIN — which is the default for all meta data created by the LOGIMPORT library, iykyk. alternatively, pmid can be PM_IN_NULL, and then pmiAddMetric will assign a unique pmid for you. super convenient... except it means the pmid stays opaque forever 😭 so your application must use pmiPutValue(3) or pmiPutValueHandle(3), and it cannot use pmiPutResult(3) to add data values to the PCP archive. choose wisely bestie.

type defines the data type of the metric, and it must be one of the PM_TYPE_... values defined in <pcp/import.h>. no substitutions, no improvising 💀

the instance domain for the metric is defined by indom, and it may be PM_INDOM_NULL for a metric with a singular value. otherwise, the value for indom would normally be constructed using the pmInDom_build macro, e.g. pmInDom_build(LOGIMPORT,0) for the first instance domain in the Performance Metrics Domain LOGIMPORT — again, the default for all meta data created by the LOGIMPORT library. and here's the cute part: multiple metrics can share the same instance domain if they have values for a similar (or more usually, identical) set of instances. sharing is caring 💖

the semantics of the metric — counter, instantaneous value, etc. — is specified by the sem argument, which would normally be the result of a call to the convenience constructor methods pmiUnits(3) or pmiExtraUnits(3). iconic.

---

🔥 DIAGNOSTICS 🔥

pmiAddMetric returns zero on success. otherwise it hands you back a negative value, which you can turn into an actual readable error message by calling pmiErrStr(3). so don't just stare at the negative number, bestie, go get the message 🙈

---

👑 SEE ALSO 👑

PCPIntro(1), LOGIMPORT(3), PMAPI(3), pmLookupDesc(3), pmiErrStr(3), pmiExtraUnits(3), pmiPutLabel(3), pmiPutResult(3), pmiPutText(3), pmiPutValue(3), pmiPutValueHandle(3) and pmiUnits(3).

---

and that's the whole page, bestie! 💜 this one's brought to you by Performance Co-Pilot, and yeah, it's literally titled PMIADDMETRIC(3) — go slay your metrics, you got this ⭐🌸