--- name: "pmdaInstance" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmdaInstance" --- # pmdaInstance(3) return instance descriptions for a PMDA ## NAME **pmdaInstance** - return instance descriptions for a PMDA ## C SYNOPSIS **#include \**\ **#include \** **int pmdaInstance(pmInDom** *indom***,** **int** *inst***,** **char \****name***,** **pmInResult \*\****result***,** **pmdaExt \****pmda***);** **cc ... -lpcp\_pmda -lpcp** ## DESCRIPTION **pmdaInstance** uses the standard [**PMDA**(3)](/PMDA/3.md) data structures to return information concerning the instance domain *indom*. The *result* structure is constructed by **pmdaInstance** and will contain one or more instance names and/or identifiers as specified by the *inst* and *name* arguments. If *inst* has the value **PM\_IN\_NULL** and *name* is a null string, *result* will contain all the instances names and identifiers in the instance domain. If *inst* is **PM\_IN\_NULL** but *name* is the name of an instance in the instance domain *indom*, then *result* will contain the instance identifier for instance *name*. Note that if *name* contains no spaces, partial matching up to the first space in the instance name is performed, i.e. \`\`**1**'' will match instance name \`\`**1** **minute**''. If *name* contains an embedded space, then no partial matching is performed and *name* should match one of the instance names exactly. If *name* is a null string but *inst* is an instance identifier in the instance domain *indom*, then *result* will contain the name for instance *inst*. The *result* structure is allocated with [**malloc**(3)](/malloc/3.md) and should be released by the caller with [**free**(3)](/free/3.md). ## MULTI-DIMENSIONAL INSTANCE NAMING Further to the above description of *name*, the set of rules describing external instance names is provided in the [**pmdaCacheStore**(3)](/pmdaCacheStore/3.md) manual page. Instance domains adds another dimension (set of values) to metrics. However, this may not suffice to describe complex multi-dimensional instance domain situations. For this case the approach used by a number of PMDAs is to structure the external instance names using a delimiter (\`\`/'' or \`\`::'' are most commonly used) to allow separation of the other dimensions. In this situation, instance domain labels should be used to define names for each instance name component. This allows [**PMAPI**(3)](/PMAPI/3.md) client tools to identify and refine value fetches to specific dimensions of interest. For example, some of the Linux kernel cgroup (control group) metric instance domains are multi-dimensional. The instance domain represents individual values across both control groups and CPUs, making this a two-dimensional instance domain. The instance names associated with this cgroup metrics indom have been structured using the \`\`::'' delimiter to separate the two dimensions. The instance domain itself has been labeled accordingly, as follows. ``` $ pminfo --desc --fetch --labels cgroup.cpuacct.usage_percpu cgroup.cpuacct.usage_percpu Data Type: 64-bit unsigned int InDom: 3.22 0xc00016 Semantics: counter Units: nanosec inst [0 or "/::cpu0"] value 713787 inst [1 or "/::cpu1"] value 353969 inst [2 or "/app::cpu0"] value 407816 inst [3 or "/app::cpu1"] value 202747 inst [0 or "/::cpu0"] labels {"device_type":"cpu","cgroup":"/","cpu":0} inst [1 or "/::cpu1"] labels {"device_type":"cpu","cgroup":"/","cpu":1} inst [2 or "/app::cpu0"] labels {"device_type":"cpu","cgroup":"/app","cpu":0} inst [3 or "/app::cpu1"] labels {"device_type":"cpu","cgroup":"/app","cpu":1} ``` ``` $ pminfo --labels 3.22 InDom: 3.22 0xc00016 labels {"device_type":"cpu"} ``` As shown above the individual instances inherit the labels from the instance domain, and the PMDA also applies additional per-instance labels describing individual cgroup and CPU names. When this model has been used by the PMDA, PMAPI clients are able to restrict their queries to the cgroup metric instances - in the example, restricting to processor "cpu0" using the "cpu" label, perhaps, or to just the "/app" cgroup metrics using the "cgroup" label. Furthermore, using this labeling scheme client tools can also correlate related instances across different instance domains. ``` $ pminfo --desc --fetch --labels kernel.percpu.cpu.irq.soft kernel.percpu.cpu.irq.soft Data Type: 64-bit unsigned int InDom: 60.0 0xf000000 Semantics: counter Units: millisec inst [0 or "cpu0"] value 6770 inst [1 or "cpu1"] value 100 inst [0 or "cpu0"] labels {"device_type":"cpu"} inst [1 or "cpu1"] labels {"device_type":"cpu"} ``` ``` $ pminfo --labels 60.0 InDom: 60.0 0xf000000 labels {"device_type":"cpu"} ``` Although these two metrics have different instance domains (*60.0* and *3.22* respectively) and are sourced from different PMDAs, the "device\_type" label identifies the common device to which these values relate. ## CAVEAT The PMDA must be using **PMDA\_INTERFACE\_2** or later, as specified in the call to [**pmdaDSO**(3)](/pmdaDSO/3.md) or [**pmdaDaemon**(3)](/pmdaDaemon/3.md). If labeling of multi-dimensional instance names is performed, the PMDA must use **PMDA\_INTERFACE\_7** or later. Because of optional partial matching up to the first space in the instance name, the **PMDA** developer should ensure that if instance names are allowed to have spaces, the names are unique up to the first space. ## DIAGNOSTICS If any errors occur during the execution of **pmdaInstance**, the *result* structure is deallocated. If the instance domain *indom* is not supported by the PMDA, **pmdaInstance** will return **PM\_ERR\_INDOM**. If the *inst* or *name* does not correspond to any instances in the *indom* domain, **pmdaInstance** will return **PM\_ERR\_INST**. ## SEE ALSO [**malloc**(3)](/malloc/3.md), [**PMAPI**(3)](/PMAPI/3.md), [**PMDA**(3)](/PMDA/3.md), [**pmdaCacheStore**(3)](/pmdaCacheStore/3.md), [**pmdaLabel**(3)](/pmdaLabel/3.md) and [**pmGetInDom**(3)](/pmGetInDom/3.md).