1PMDAINSTANCE(3) Library Functions Manual PMDAINSTANCE(3)
2
6 pmdaInstance - return instance descriptions for a PMDA
7
9 #include <pcp/pmapi.h>
10 #include <pcp/pmda.h>
11 int pmdaInstance(pmInDom indom, int inst, char *name,
13 pmInResult **result, pmdaExt *pmda);
14 cc ... -lpcp_pmda -lpcp
16
18 pmdaInstance uses the standard PMDA(3) data structures to return infor‐
19 mation concerning the instance domain indom.
20 The result structure is constructed by pmdaInstance and will contain
22 one or more instance names and/or identifiers as specified by the inst
23 and name arguments.
24 If inst has the value PM_IN_NULL and name is a null string, result will
26 contain all the instances names and identifiers in the instance domain.
27 If inst is PM_IN_NULL but name is the name of an instance in the in‐
29 stance domain indom, then result will contain the instance identifier
30 for instance name. Note that if name contains no spaces, partial
31 matching up to the first space in the instance name is performed, i.e.
32 ``1'' will match instance name ``1 minute''. If name contains an em‐
33 bedded space, then no partial matching is performed and name should
34 match one of the instance names exactly.
35 If name is a null string but inst is an instance identifier in the in‐
37 stance domain indom, then result will contain the name for instance in‐
38 st. The result structure is allocated with malloc(3) and should be re‐
39 leased by the caller with free(3).
40
42 Further to the above description of name, the set of rules describing
43 external instance names is provided in the pmdaCacheStore(3) manual
44 page.
45 Instance domains adds another dimension (set of values) to metrics.
47 However, this may not suffice to describe complex multi-dimensional in‐
48 stance domain situations. For this case the approach used by a number
49 of PMDAs is to structure the external instance names using a delimiter
50 (``/'' or ``::'' are most commonly used) to allow separation of the
51 other dimensions. In this situation, instance domain labels should be
52 used to define names for each instance name component. This allows
53 PMAPI(3) client tools to identify and refine value fetches to specific
54 dimensions of interest.
55 For example, some of the Linux kernel cgroup (control group) metric in‐
57 stance domains are multi-dimensional. The instance domain represents
58 individual values across both control groups and CPUs, making this a
59 two-dimensional instance domain. The instance names associated with
60 this cgroup metrics indom have been structured using the ``::'' delim‐
61 iter to separate the two dimensions. The instance domain itself has
62 been labeled accordingly, as follows.
63 $ pminfo --desc --fetch --labels cgroup.cpuacct.usage_percpu
65 cgroup.cpuacct.usage_percpu
66 Data Type: 64-bit unsigned int InDom: 3.22 0xc00016
67 Semantics: counter Units: nanosec
68 inst [0 or "/::cpu0"] value 713787
69 inst [1 or "/::cpu1"] value 353969
70 inst [2 or "/app::cpu0"] value 407816
71 inst [3 or "/app::cpu1"] value 202747
72 inst [0 or "/::cpu0"] labels {"device_type":"cpu","cgroup":"/","cpu":0}
73 inst [1 or "/::cpu1"] labels {"device_type":"cpu","cgroup":"/","cpu":1}
74 inst [2 or "/app::cpu0"] labels {"device_type":"cpu","cgroup":"/app","cpu":0}
75 inst [3 or "/app::cpu1"] labels {"device_type":"cpu","cgroup":"/app","cpu":1}
76 $ pminfo --labels 3.22
78 InDom: 3.22 0xc00016
79 labels {"device_type":"cpu"}
80 As shown above the individual instances inherit the labels from the in‐
82 stance domain, and the PMDA also applies additional per-instance labels
83 describing individual cgroup and CPU names. When this model has been
84 used by the PMDA, PMAPI clients are able to restrict their queries to
85 the cgroup metric instances - in the example, restricting to processor
86 "cpu0" using the "cpu" label, perhaps, or to just the "/app" cgroup
87 metrics using the "cgroup" label.
88 Furthermore, using this labeling scheme client tools can also correlate
90 related instances across different instance domains.
91 $ pminfo --desc --fetch --labels kernel.percpu.cpu.irq.soft
93 kernel.percpu.cpu.irq.soft
94 Data Type: 64-bit unsigned int InDom: 60.0 0xf000000
95 Semantics: counter Units: millisec
96 inst [0 or "cpu0"] value 6770
97 inst [1 or "cpu1"] value 100
98 inst [0 or "cpu0"] labels {"device_type":"cpu"}
99 inst [1 or "cpu1"] labels {"device_type":"cpu"}
100 $ pminfo --labels 60.0
102 InDom: 60.0 0xf000000
103 labels {"device_type":"cpu"}
104 Although these two metrics have different instance domains (60.0 and
106 3.22 respectively) and are sourced from different PMDAs, the "de‐
107 vice_type" label identifies the common device to which these values re‐
108 late.
109
111 The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the
112 call to pmdaDSO(3) or pmdaDaemon(3). If labeling of multi-dimensional
113 instance names is performed, the PMDA must use PMDA_INTERFACE_7 or lat‐
114 er.
115 Because of optional partial matching up to the first space in the in‐
117 stance name, the PMDA developer should ensure that if instance names
118 are allowed to have spaces, the names are unique up to the first space.
119
121 If any errors occur during the execution of pmdaInstance, the result
122 structure is deallocated. If the instance domain indom is not support‐
123 ed by the PMDA, pmdaInstance will return PM_ERR_INDOM.
124 If the inst or name does not correspond to any instances in the indom
126 domain, pmdaInstance will return PM_ERR_INST.
127
129 malloc(3), PMAPI(3), PMDA(3), pmdaCacheStore(3), pmdaLabel(3) and
130 pmGetInDom(3).
131Performance Co-Pilot PCP PMDAINSTANCE(3)