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

NAME

6       pmLookupLabels,  pmGetInstancesLabels, pmGetItemLabels, pmGetClusterLa‐
7       bels,   pmGetInDomLabels,   pmGetDomainLabels,   pmGetContextLabels   -
8       retrieve labels associated with performance metric values
9

C SYNOPSIS

11       #include <pcp/pmapi.h>
12
13       int pmLookupLabels(pmID pmid, pmLabelSet **labelsets);
14
15       int pmGetInstancesLabels(pmInDom indom, pmLabelSet **labelsets);
16       int pmGetItemLabels(pmID pmid, pmLabelSet **labelsets);
17       int pmGetClusterLabels(pmID pmid, pmLabelSet **labelsets);
18       int pmGetInDomLabels(pmInDom indom, pmLabelSet **labelsets);
19       int pmGetDomainLabels(int domain, pmLabelSet **labelsets);
20       int pmGetContextLabels(pmLabelSet **labelsets);
21
22       cc ... -lpcp
23

PYTHON SYNOPSIS

25       from pcp import pmapi
26
27       labelsets = pmapi.pmContext().pmLookupLabels(pmid)
28
29       labelsets = pmapi.pmContext().pmGetInstancesLabels(indom)
30       labelsets = pmapi.pmContext().pmGetItemLabels(pmid)
31       labelsets = pmapi.pmContext().pmGetClusterLabels(pmid)
32       labelsets = pmapi.pmContext().pmGetInDomLabels(indom)
33       labelsets = pmapi.pmContext().pmGetDomainLabels(domain)
34       labelsets = pmapi.pmContext().pmGetContextLabels()
35
36

DESCRIPTION

38       Labels  are  name:value pairs associated with performance metric values
39       for the purpose of attaching  additional  metric  metadata  to  values.
40       This  metadata  is  less structured and exists separately to the metric
41       descriptor available for every PCP metric from pmLookupDesc(3).
42
43       Much like the metric descriptor metadata, labels are an  integral  part
44       of the identity of each metric, and should rarely, if ever, change.
45
46       The   pmLookupLabels  routine  is  a  convenience  interface  providing
47       retrieval for all labels associated with a  single  performance  metric
48       identifier, pmid.  It performs no caching of labels internally.
49
50       For  efficiency  in communication and storage within the various compo‐
51       nents of the PMCS (Performance Metrics Collection System),  labels  are
52       maintained  using  a  hierarchy.  The set of labels associated with any
53       individual metric value consists of the union of labels  from  each  of
54       these sets of labels:
55
56       1.  Global  labels  (apply  to all metric values from a host or archive
57       context)
58
59       pmGetContextLabels
60               provides the labelset associated with all metric values from  a
61               given source (PMAPI context).
62
63       2. Domain labels (apply to every metric within a PMDA)
64
65       pmGetDomainLabels
66               provides the labelset associated with the domain identifier.
67
68       3. Instance Domain labels (apply to all metrics sharing that indom)
69
70       pmGetInDomLabels
71               provides the labelset associated with the instance domain iden‐
72               tifier indom.
73
74       4. Cluster labels (apply to a group of metrics within one domain)
75
76       pmGetClusterLabels
77               provides  the  labelset  associated  with  the  metric  cluster
78               (domain,cluster) identified by pmid.
79
80       5. Item labels (apply to an individual performance metric)
81
82       pmGetItemLabels
83               provides   the   labelset   associated  with  the  metric  item
84               (domain,cluster,item) identified by pmid.
85
86       6. Instance labels (apply to individual instances of a metric)
87
88       pmGetInstancesLabels
89               provides  the  set  of  instance  identifiers  and  labels   in
90               labelsets for each instance associated with the instance domain
91               identifier indom.  The return value  indicates  the  number  of
92               elements in the result - one labelset for each instance.
93
94       These  independent labelsets can be merged using pmMergeLabelSets(3) to
95       form the complete set of all labels associated with a given value.
96

LABEL SYNTAX

98       Labels are stored and communicated within PCP using JSONB format.  This
99       format  is  a  restricted  form of JSON suitable for indexing and other
100       operations.  In JSONB form, insignificant whitespace is discarded,  and
101       the  order  of label names is not preserved.  Within the PMCS a lexico‐
102       graphically sorted key space is always maintained, however.   Duplicate
103       label  names  are  not permitted.  The label with highest precedence is
104       the only one presented.  If duplicate names are presented at  the  same
105       hierarchy  level, only one will be preserved (exactly which one wins is
106       arbitrary, so do not rely on this).
107
108       All name:value pair(s) present will be  converted  to  JSONB  form  and
109       merged  with  the existing set of labels for the requested entity (con‐
110       text, domain, indom, metric or instance).
111
112       The label names are further  constrained  to  the  same  set  of  rules
113       defined for PMNS subtree names.
114
115       Each component in a label name must begin with an alphabetic character,
116       and be followed by zero or more characters drawn from the  alphabetics,
117       the  digits and the underscore (``_'') character.  For alphabetic char‐
118       acters in a name, upper and lower case are distinguished.
119
120       The value of a label offers significantly more freedom, and may be  any
121       valid  value  as  defined  by the JSON (http://json.org) specification.
122       Redundant whitespace is always removed within the PMCS.
123

PRECEDENCE

125       The complete set of labels associated with any metric  value  is  built
126       from  several  sources and duplicate label names may exist at any point
127       in the source hierarchy.  However, when evaluating the label set (merg‐
128       ing  labels  from the different sources) the JSONB concept of only pre‐
129       senting unique labels is used.  It is  therefore  important  to  define
130       precedence  rules  in  order that a deterministic set of uniquely named
131       labels can be defined.
132
133       As a rule of thumb, the labels closest to PMNS leaf  nodes  and  metric
134       values take precedence:
135
136       1. Global context labels
137           (as reported by the pmcd.labels metric) are the lowest precedence.
138
139       2. Domain labels
140           (for  all  metrics  and instances from a PMDA) are the next highest
141           precedence.
142
143       3. Instance Domain labels
144           associated with an InDom are the next highest precedence.
145
146       4. Metric cluster labels
147           associated with a PMID cluster are the next highest precedence.
148
149       5. Metric item labels
150           associated with an individual PMID are the next highest precedence.
151
152       6. Instance labels
153           associated with a metric instance identifier  have  highest  prece‐
154           dence.
155

DATA STRUCTURES

157       The  primary  output  from  pmLookupLabels  is returned in the argument
158       labelset as an array, using the following component data structures;
159
160            struct {
161                uint     name : 16;      /* label name offset in JSONB string */
162                uint     namelen : 8;    /* length of name excluding the null */
163                uint     flags : 8;      /* information about this label */
164                uint     value : 16;     /* offset of the label value */
165                uint     valuelen : 16;  /* length of value in bytes */
166            } pmLabel;
167
168            struct {
169                uint     inst;           /* PM_IN_NULL or the instance ID */
170                int      nlabels;        /* count of labels or error code */
171                char     *json;          /* JSON formatted labels string */
172                uint     jsonlen : 16;   /* JSON string length byte count */
173                uint     padding : 16;   /* zero, reserved for future use */
174                pmLabel  *labels;        /* indexing into the JSON string */
175            } pmLabelSet;
176
177       The pmLabel provides  information  about  an  individual  label.   This
178       includes  the  offsets  to  the start of its name and value in the json
179       string of a pmLabelSet, their respective lengths, and also any informa‐
180       tive  flags  associated with the label (describing where it lies in the
181       hierarchy of labels, and  whether  it  is  an  intrinsic  or  extrinsic
182       label).
183
184       Building  on this, the pmLabelSet provides information about the set of
185       labels associated with an entity (context, domain, indom, metric  clus‐
186       ter,  item  or instance).  The entity will be from any one level of the
187       label hierarchy.  If at the lowest hierarchy level (which happens to be
188       highest  precedence - PM_LABEL_INSTANCES) then the inst field will con‐
189       tain an actual instance identifier instead of PM_IN_NULL.
190
191       The nlabels field describes the number  of  labels  (name:value  pairs)
192       that  can be found in both the accompanying json string (which is JSONB
193       format - no unnecessary whitespace and with no duplicate  label  names)
194       and the accompanying labels array (which has nlabels elements).
195

EXAMPLES

197       Consider  a  deployment  with global labels (assume $PCP_SYSCONF_DIR is
198       set to its usual location of /etc/pcp) as follows:
199
200       $ cat /etc/pcp/labels/*
201       {
202         "tier": "production",
203         "datacenter": "hkg",
204         "services": ["indexer","database"]
205       }
206
207       Use pminfo to form the merged labelsets for several pmdasample(1)  met‐
208       rics as follows:
209
210       $ pminfo -m -f --labels sample.rapid sample.colour sample.mirage
211
212       sample.rapid PMID: 30.0.64
213            value 800000000
214            labels {"agent":"sample","datacenter":"sydney","hostname":"acme.com","measure":"speed","role":"testing","services":["indexer","database"],"tier":"production","units":"metres per second","unitsystem":"SI"}
215
216       sample.colour PMID: 30.0.5
217            inst [0 or "red"] value 101
218            inst [1 or "green"] value 202
219            inst [2 or "blue"] value 303
220            inst [0 or "red"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"}
221            inst [1 or "green"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"}
222            inst [2 or "blue"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"}
223
224       sample.mirage PMID: 29.0.37
225            inst [0 or "m-00"] value 99
226            inst [0 or "m-00"] labels {"agent":"sample","datacenter":"sydney","hostname":"acme.com","role":"testing","services":["indexer","database"],"tier":"production","transient":false}
227
228       Here,  pminfo  has  merged  the  separate  sets of labels returned from
229       pmGetContextLabels  (names:  datacenter,  hostname,  services,   tier),
230       pmGetDomainLabels   (names:   role,  agent),  pmGetInDomLabels  (names:
231       model), pmGetItemLabels (names: units, unitsystem) and  pmGetInstances‐
232       Labels (names: transient) to form the complete set for each of the met‐
233       rics.
234

DIAGNOSTICS

236       On success these interfaces all return the number of  elements  in  the
237       labelsets  array.   associated  with  performance  metrics.  The memory
238       associated with labelsets should be released  using  pmFreeLabelSets(3)
239       when no longer needed.
240
241       Only  in  the  case  of pmLookupLabels will the resulting labelset be a
242       merged set of labels from all hierarchy levels.
243
244       For the other routines, except for pmGetInstancesLabels, if  no  labels
245       exist  at all for the requested hierarchy level the return code will be
246       zero and no space will have been allocated.
247
248       In the case of pmGetInstancesLabels, which can return multiple elements
249       in its labelsets result (one set of labels for each instance), the nla‐
250       bels field may be either zero indicating no labels for  that  instance,
251       or a positive count of labels, or a negative PMAPI error code.
252
253       Note that it is mandatory for a call to pmGetInstancesLabels to be pre‐
254       ceded by a call to pmGetInDom(3) to  ensure  the  instances  have  been
255       resolved within the PMDA.
256
257       If no result can be obtained, e.g. due to IPC failure using the current
258       PMAPI context then pmGetInstancesLabels will return  a  negative  error
259       code which may be examined using
260
261       A successful return from the Python API always provides the labelset in
262       the form of a list, for all labels functions.  On error a pmErr  excep‐
263       tion is raised containing the error code and diagnostic.  pmErrStr(3).
264

SEE ALSO

266       pmcd(1),    PMAPI(3),   pmFetch(3),   pmGetInDom(3),   pmLookupDesc(3),
267       pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3) and  pmNewCon‐
268       text(3).
269
270
271
272Performance Co-Pilot                  PCP                    PMLOOKUPLABELS(3)
Impressum