PMNS(5)

💅 PMNS — the performance metrics name space

okay bestie, gather round, because this is the page for the file format that literally names every metric in PCP. it's the PMNS(5) page, living in the File Formats Manual, and it's giving absolute backbone-of-the-whole-system energy. let's go 🦋

---

✨ SYNOPSIS ✨

$PCP_VAR_DIR/pmns

that's it. that's the vibe. one path and a dream 💖

---

🌸 DESCRIPTION 🌸

so when you're using the Performance Metrics Programming Interface (PMAPI) of the Performance Co-Pilot (PCP), every performance metric gets two identities, like a celebrity with a stage name and a legal name:

• an external name, living in a hierarchic Performance Metrics Name Space (PMNS)
• an internal identifier, aka the Performance Metric Identifier (PMID)

and a PMNS is literally just the matchmaking service that says "this name ➡️ this PMID." no cap.

a PMNS gets defined across one or more ASCII source files. iconic.

loading one? you call pmLoadNameSpace(3) or pmLoadASCIINameSpace(3). those are the girlies doing the work 🫶

now, important lore: as of Version 3.10.3 of PCP, duplicate names for the same PMID are allowed in the PMNS by default. yes, you heard me. but pmLoadASCIINameSpace(3) hands you an alternative interface where you get user-defined control over how duplicate names get processed. main character choice, honestly.

the external format for a PMNS follows the syntax and semantics described in the sections below. keep reading bestie, it's all here.

there's one default PMNS in the files below $PCP_VAR_DIR/pmns — but users and application developers are totally free to create and use alternate PMNS's. for an example of that, go peek at the PCP Tutorial in $PCP_DEMOS_DIR/Tutorial. so cute.

and ngl, even though an application can call pmLoadNameSpace(3), normally that only happens directly for the -n command line option, where an explicit root PMNS file is specified. since PCP version 2 uses a distributed PMNS (more on that below 👇), an application can extract PMNS info from a host's PMCD or from an archive. but — and this is the plot twist — if the PMNS source is a version 1 archive (see PCPIntro(1)), then the local PMNS will be loaded using the path specified by the environment variable PMNS_DEFAULT. 💀

---

🌈 DISTRIBUTED PMNS 🌈

in PCP version 1, the PMNS functions in the API all operated on a PMNS loaded locally from a file. very "living at home" era.

since PCP version 2, though? glow up. PMNS functions may get the PMNS information remotely from a PMCD, or directly from the meta data of an archive. periodt.

---

🎀 PROCESSING FRAMEWORK 🎀

before anything else happens, the PMNS specification gets passed through pmcpp(1). so all of this is available to you in the spec:

• C-style comments
• #include directives
• #define directives and macro substitution
• conditional processing via #ifdef ... #endif, etc.

when pmcpp(1) runs, the "standard" include directories are the current directory and $PCP_VAR_DIR/pmns. iykyk.

the preprocessing with pmcpp(1) may be omitted in some cases where the PMNS is known to not contain any C-style comments, preprocessor directives or macros. refer to the descriptions of pmLoadASCIINameSpace(3) and pmLoadNameSpace(3) for the details, bestie — don't skip that part.

---

🦋 SYNTAX 🦋

the general syntax for a non-leaf node in the PMNS goes like this:

pathname {
        name      [pmid]
        ...
}

where pathname is the full pathname from the root of the PMNS to this non-leaf node, with each component in the pathname separated by a .. the root node for the PMNS must have the special name root, but the common prefix root. must be omitted from all pathnames. yes, always. no exceptions 💅

each component in the pathname is drawn from the ASCII(7) character set, beginning with an alphabetic character, and followed by zero or more characters drawn from the alphabetics, the digits, and the underscore _ character. and for alphabetic characters in a pathname component? upper and lower case are distinguished. so Cpu and cpu are not the same girl, okay?? 😭

non-leaf nodes in the PMNS may be defined in any order. chaotic but valid.

the descendent nodes are defined by the set of names, relative to the pathname of their parent non-leaf node. for those descendent nodes: leaf nodes have a pmid specification, non-leaf nodes do not. that's the whole distinction, slay.

the syntax for the pmid specification was chosen to help manage the allocation of PMIDs across disjoint and autonomous domains of administration and implementation. each pmid consists of 3 integer parts, separated by colons, e.g. 14:27:11.

this hierarchic numbering scheme is intended to mirror the implementation hierarchy of:

• performance metric domain
• metrics cluster (data structure or operational similarity)
• individual metric

in practice, the two leading components are likely to be macros in the PMNS specification source, and pmcpp(1) will convert the macros to integers. those macros for the initial components of the pmid are likely to be defined either in a standard include file — e.g. $PCP_VAR_DIR/pmns/stdpmid — or in the current source file. ✨

💜 dynamic metrics 💜

to support dynamic metrics, where the existence of a metric is known to a PMDA but not visible in the PMNS, there's a variant syntax for the pmid, namely a domain number followed by asterisks for the other components of the pmid, e.g. 14:*:*.

the corresponding metric name forms the root of a subtree of dynamic metric names defined in the corresponding PMDA, as identified by the domain number. obsessed.

👑 the current allocation of the high-order (PMD or domain) component of PMIDs 👑

• 0 — reserved
• 1-384 — production PMDAs from PCP packages
• 385-510 — end-user PMDAs (allocate from high to low)
• 511 — reserved for dynamic PMNS entries

bestie, note that end-user PMDAs allocate from high to low and 511 is reserved for dynamic PMNS entries. don't just grab a number, that's rude 🙈

---

🌟 EXAMPLE 🌟

here's the whole thing in its natural habitat, verbatim, no notes:

#define KERNEL 1
#define FOO 387
root {
    network
    cpu
    dynamic     FOO:*:*
}

#define NETWORK 26
network {
    intrate     KERNEL:NETWORK:1
    packetrate
}

network.packetrate {
    in          KERNEL:NETWORK:35
    out         KERNEL:NETWORK:36
}

#define CPU 10
cpu {
    syscallrate KERNEL:CPU:10
    util
}

#define USER 20
#define SYSTEM 21
#define IDLE 22

cpu.util {
    user        KERNEL:CPU:USER
    sys         KERNEL:CPU:SYSTEM
    idle        KERNEL:CPU:IDLE
}

ate. no crumbs. 🔥

---

💖 SEE ALSO 💖

PCPIntro(1), pmcd(1), pmcpp(1), PCPIntro(3), PMAPI(3), pmErrStr(3), pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pcp.conf(5) and pcp.env(5).

---

and that's the whole page, bestie 🥹 this one came to you straight from Performance Co-Pilot, PCP — so go forth and name your metrics, be kind to your PMIDs, and remember: leaf nodes get a pmid, non-leaf nodes do not. mwah 💋🎀