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, except labels at the instances level.  Labels at the
49       instances  level  must  be  retrieved  separately  with   a   call   to
50       pmGetInstancesLabels because different metric instances may have labels
51       with the same label name.   The  pmLookupLabels  function  performs  no
52       caching of labels internally.
53
54       For  efficiency  in communication and storage within the various compo‐
55       nents of the PMCS (Performance Metrics Collection System),  labels  are
56       maintained  using  a  hierarchy.  The set of labels associated with any
57       individual metric value consists of the union of labels  from  each  of
58       these sets of labels:
59
60       1.  Global  labels  (apply  to all metric values from a host or archive
61       context)
62
63       pmGetContextLabels
64               provides the labelset associated with all metric values from  a
65               given source (PMAPI context).
66
67       2. Domain labels (apply to every metric within a PMDA)
68
69       pmGetDomainLabels
70               provides the labelset associated with the domain identifier.
71
72       3. Instance Domain labels (apply to all metrics sharing that indom)
73
74       pmGetInDomLabels
75               provides the labelset associated with the instance domain iden‐
76               tifier indom.
77
78       4. Cluster labels (apply to a group of metrics within one domain)
79
80       pmGetClusterLabels
81               provides  the  labelset  associated  with  the  metric  cluster
82               (domain,cluster) identified by pmid.
83
84       5. Item labels (apply to an individual performance metric)
85
86       pmGetItemLabels
87               provides   the   labelset   associated  with  the  metric  item
88               (domain,cluster,item) identified by pmid.
89
90       6. Instance labels (apply to individual instances of a metric)
91
92       pmGetInstancesLabels
93               provides  the  set  of  instance  identifiers  and  labels   in
94               labelsets for each instance associated with the instance domain
95               identifier indom.  The return value  indicates  the  number  of
96               elements in the result - one labelset for each instance.
97
98       These  independent labelsets can be merged using pmMergeLabelSets(3) to
99       form the complete set of all labels  associated  with  a  given  value.
100       Note  that  the label sets returned by pmGetInstancesLabels can be tra‐
101       versed but should not be merged because the label names are unlikely to
102       be unique for different instances of the given indom.
103

LABEL SYNTAX

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

PRECEDENCE

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

DATA STRUCTURES

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

EXAMPLES

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

PYTHON EXAMPLE

243       #!/usr/bin/env pmpython
244
245       import sys
246       from pcp import pmapi
247       import cpmapi as c_api
248
249       ctx = pmapi.pmContext(c_api.PM_CONTEXT_HOST, "local:")
250
251       for metric in sys.argv[1:]:
252           pmid = ctx.pmLookupName(metric)[0]
253           desc = ctx.pmLookupDescs(pmid)[0]
254
255           print("== label sets for %s ==" % metric)
256           labelSetList = ctx.pmLookupLabels(pmid)
257           # class pmLabelSet has a __str__ handler
258           for labelSet in labelSetList:
259               print("%s" % labelSet)
260           ctx.pmFreeLabelSets(labelSetList)
261
262           if desc.contents.indom != c_api.PM_INDOM_NULL:
263               print("== instances label sets for %s ==" % metric)
264               labelSetList = ctx.pmGetInstancesLabels(desc.contents.indom)
265               for labelSet in labelSetList:
266                   print("%s" % labelSet)
267               ctx.pmFreeLabelSets(labelSetList)
268

DIAGNOSTICS

270       On  success  these  interfaces all return the number of elements in the
271       labelsets array.  associated  with  performance  metrics.   The  memory
272       associated  with  labelsets should be released using pmFreeLabelSets(3)
273       when no longer needed.
274
275       Only in the case of pmLookupLabels will the  resulting  labelset  be  a
276       merged set of labels from all hierarchy levels (except at the instances
277       level, as described above).
278
279       For the other routines, except for pmGetInstancesLabels, if  no  labels
280       exist  at all for the requested hierarchy level the return code will be
281       zero and no space will have been allocated.
282
283       In the case of pmGetInstancesLabels, which can return multiple elements
284       in its labelsets result (one set of labels for each instance), the nla‐
285       bels field may be either zero indicating no labels for  that  instance,
286       or a positive count of labels, or a negative PMAPI error code.
287
288       Note that it is mandatory for a call to pmGetInstancesLabels to be pre‐
289       ceded by a call to pmGetInDom(3) to  ensure  the  instances  have  been
290       resolved within the PMDA.
291
292       If no result can be obtained, e.g. due to IPC failure using the current
293       PMAPI context then pmGetInstancesLabels will return  a  negative  error
294       code which may be examined using
295
296       A successful return from the Python API always provides the labelset in
297       the form of a list, for all labels functions.  On error a pmErr  excep‐
298       tion is raised containing the error code and diagnostic.  pmErrStr(3).
299

SEE ALSO

301       pmcd(1),    PMAPI(3),   pmFetch(3),   pmGetInDom(3),   pmLookupDesc(3),
302       pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3) and  pmNewCon‐
303       text(3).
304
305
306
307Performance Co-Pilot                  PCP                    PMLOOKUPLABELS(3)
Impressum