PMTRIMNAMESPACE(3)

💖 PMTRIMNAMESPACE 💖

okay bestie, we're doing pmTrimNameSpace(3) from the Library Functions Manual and honestly? it's giving ✨ spring cleaning for your metrics ✨. no cap.

---

🌸 NAME 🌸

pmTrimNameSpace — prune a performance metrics name space 🪴✂️

---

🎀 C SYNOPSIS 🎀

#include <pcp/pmapi.h>

int pmTrimNameSpace(void);

cc ... -lpcp

like, that's the whole thing. one function. no arguments. she's simple, she's elegant, she eats 💅

---

✨ DESCRIPTION ✨

so here's the tea, bestie 🍓. in some (rare) cases — like, genuinely rare, don't come for me — it's actually helpful to prune the Performance Metrics Name Space (PMNS) so it matches the metrics that are actually available. vibe check your namespace, basically. 🔥

the default PMNS that a Performance Metrics Application Programming Interface (PMAPI) client can access is provided by the current PMAPI context, and it depends on which flavor of context you've got going on:

• for a PMAPI context of type PM_CONTEXT_HOST, the PMNS is provided by pmcd(1) on the associated host, and no pruning is required — she's already fresh ✨
• for a PMAPI context of type PM_CONTEXT_ARCHIVE, the PMNS is stored within the associated Performance Co-Pilot (PCP) archive, and again, no pruning is required 💖
• for a PMAPI context of type PM_CONTEXT_LOCAL, at the first PMAPI call that needs access to the PMNS, it gets loaded from the default local location $PCP_VAR_DIR/pmns/root (or $PMNS_DEFAULT), and — say it with me — no pruning is required 🎀

if the default PMNS is in effect, then calling pmTrimNameSpace is a no-op and returns zero, with no change to the PMNS. she literally does nothing and she's valid for it 🙈

but wait, there's more 👑. PMAPI clients also have the option of over-riding that default PMNS by loading a local PMNS from a file — peep PMNS(5) for the format, iykyk — by calling pmLoadASCIINameSpace(3) or pmLoadNameSpace(3). that's the situation where some PMNS pruning might actually be useful. main character moment fr fr.

if a local PMNS is in effect when pmTrimNameSpace gets called, then the first thing she does is restore the PMNS to the state as of the completion of the last pmLoadASCIINameSpace(3) or pmLoadNameSpace(3). this is so that the effects of consecutive calls to pmTrimNameSpace are not additive — no stacking, no compounding, we reset every time bestie 🧚

after that reset, what pmTrimNameSpace does next depends on the type of the current PMAPI context:

• for a context of type PM_CONTEXT_ARCHIVE, the local PMNS is trimmed to exclude metrics for which no description can be found in the PCP archive. then the PMNS is further trimmed to remove empty subtrees that do not contain any performance metric 🌿. since PCP archives usually contain some subset of all the metrics named in a PMNS, pmTrimNameSpace effectively prunes the application's PMNS down to contain only the names of the metrics in the archive. decluttered. iconic. periodt. 💅
• for a context of type PM_CONTEXT_HOST or PM_CONTEXT_LOCAL, no further action is required — nothing to do, go touch grass 🌈

on success, pmTrimNameSpace returns zero. 🫶

---

💀 DIAGNOSTICS 💀

• PM_ERR_NOPMNS — there has been some earlier problem with establishing the relevant PMNS 😭 like something went sideways before you even got here
• PM_ERR_NOCONTEXT — the current PMAPI context is invalid 🚫 bestie the context is not contexting

---

🌈 SEE ALSO 🌈

pmlogger(1), PMAPI(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pmNewContext(3) and PMNS(5).

---

ngl this one's short and sweet, so go forth and prune responsibly 🦋

---

okay that's the whole page bestie, mwah 💜 this little gem comes to you from Performance Co-Pilot over at PCP — go drink some water and call pmTrimNameSpace on your own life ✨🎀🫶