1PMDAINSTANCE(3)            Library Functions Manual            PMDAINSTANCE(3)
2
3
4

NAME

6       pmdaInstance - return instance descriptions for a PMDA
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10       #include <pcp/pmda.h>
11
12       int pmdaInstance(pmInDom indom, int inst, char *name,
13               pmInResult **result, pmdaExt *pmda);
14
15       cc ... -lpcp_pmda -lpcp
16

DESCRIPTION

18       pmdaInstance uses the standard PMDA(3) data structures to return infor‐
19       mation concerning the instance domain indom.
20
21       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
25       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
28       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
36       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

MULTI-DIMENSIONAL INSTANCE NAMING

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
46       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
56       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
64       $ 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
77       $ pminfo --labels 3.22
78       InDom: 3.22 0xc00016
79            labels {"device_type":"cpu"}
80
81       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
89       Furthermore, using this labeling scheme client tools can also correlate
90       related instances across different instance domains.
91
92       $ 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
101       $ pminfo --labels 60.0
102       InDom: 60.0 0xf000000
103            labels {"device_type":"cpu"}
104
105       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

DIAGNOSTICS

111       If  any  errors  occur during the execution of pmdaInstance, the result
112       structure is deallocated.  If the instance domain indom is not support‐
113       ed by the PMDA, pmdaInstance will return PM_ERR_INDOM.
114
115       If  the  inst or name does not correspond to any instances in the indom
116       domain, pmdaInstance will return PM_ERR_INST.
117

CAVEAT

119       The PMDA must be using PMDA_INTERFACE_2 or later, as specified  in  the
120       call  to pmdaDSO(3) or pmdaDaemon(3).  If labeling of multi-dimensional
121       instance names is performed, the PMDA must use PMDA_INTERFACE_7 or lat‐
122       er.
123
124       Because  of  optional partial matching up to the first space in the in‐
125       stance name, the PMDA developer should ensure that  if  instance  names
126       are allowed to have spaces, the names are unique up to the first space.
127

SEE ALSO

129       malloc(3),   PMAPI(3),  PMDA(3),  pmdaCacheStore(3),  pmdaLabel(3)  and
130       pmGetInDom(3).
131
132
133
134Performance Co-Pilot                  PCP                      PMDAINSTANCE(3)
Impressum