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

DESCRIPTION

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

LABEL SYNTAX

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

PRECEDENCE

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

DATA STRUCTURES

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

EXAMPLES

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

DIAGNOSTICS

223       On success these interfaces all return the number of  elements  in  the
224       labelsets  array.   associated  with  performance  metrics.  The memory
225       associated with labelsets should be released  using  pmFreeLabelSets(3)
226       when no longer needed.
227
228       Only  in  the  case  of pmLookupLabels will the resulting labelset be a
229       merged set of labels from all hierarchy levels.
230
231       For the other routines, except for pmGetInstancesLabels, if  no  labels
232       exist  at all for the requested hierarchy level the return code will be
233       zero and no space will have been allocated.
234
235       In the case of pmGetInstancesLabels, which can return multiple elements
236       in its labelsets result (one set of labels for each instance), the nla‐
237       bels field may be either zero indicating no labels for  that  instance,
238       or a positive count of labels, or a negative PMAPI error code.
239
240       Note that it is mandatory for a call to pmGetInstancesLabels to be pre‐
241       ceded by a call to pmGetInDom(3) to  ensure  the  instances  have  been
242       resolved within the PMDA.
243
244       If no result can be obtained, e.g. due to IPC failure using the current
245       PMAPI context then pmGetInstancesLabels will return  a  negative  error
246       code which may be examined using pmErrStr(3).
247

SEE ALSO

249       pmcd(1),    PMAPI(3),   pmFetch(3),   pmGetInDom(3),   pmLookupDesc(3),
250       pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3) and  pmNewCon‐
251       text(3).
252
253
254
255Performance Co-Pilot                  PCP                    PMLOOKUPLABELS(3)
Impressum