1PMLOOKUPLABELS(3) Library Functions Manual PMLOOKUPLABELS(3)
2
6 pmLookupLabels, pmGetInstancesLabels, pmGetItemLabels, pmGetClusterLa‐
7 bels, pmGetInDomLabels, pmGetDomainLabels, pmGetContextLabels -
8 retrieve labels associated with performance metric values
9
11 #include <pcp/pmapi.h>
12 int pmLookupLabels(pmID pmid, pmLabelSet **labelsets);
14 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 cc ... -lpcp
23
25 from pcp import pmapi
26 labelsets = pmapi.pmContext().pmLookupLabels(pmid)
28 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
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 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 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 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 1. Global labels (apply to all metric values from a host or archive
61 context)
62 pmGetContextLabels
64 provides the labelset associated with all metric values from a
65 given source (PMAPI context).
66 2. Domain labels (apply to every metric within a PMDA)
68 pmGetDomainLabels
70 provides the labelset associated with the domain identifier.
71 3. Instance Domain labels (apply to all metrics sharing that indom)
73 pmGetInDomLabels
75 provides the labelset associated with the instance domain iden‐
76 tifier indom.
77 4. Cluster labels (apply to a group of metrics within one domain)
79 pmGetClusterLabels
81 provides the labelset associated with the metric cluster
82 (domain,cluster) identified by pmid.
83 5. Item labels (apply to an individual performance metric)
85 pmGetItemLabels
87 provides the labelset associated with the metric item
88 (domain,cluster,item) identified by pmid.
89 6. Instance labels (apply to individual instances of a metric)
91 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 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
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 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 The label names are further constrained to the same set of rules
120 defined for PMNS subtree names.
121 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 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
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 As a rule of thumb, the labels closest to PMNS leaf nodes and metric
141 values take precedence:
142 1. Global context labels
144 (as reported by the pmcd.labels metric) are the lowest precedence.
145 2. Domain labels
147 (for all metrics and instances from a PMDA) are the next highest
148 precedence.
149 3. Instance Domain labels
151 associated with an InDom are the next highest precedence.
152 4. Metric cluster labels
154 associated with a PMID cluster are the next highest precedence.
155 5. Metric item labels
157 associated with an individual PMID are the next highest precedence.
158 6. Instance labels
160 associated with a metric instance identifier have highest prece‐
161 dence.
162
164 The primary output from pmLookupLabels is returned in the argument
165 labelset as an array, using the following component data structures;
166 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 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 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 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 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
204 Consider a deployment with global labels (assume $PCP_SYSCONF_DIR is
205 set to its usual location of /etc/pcp) as follows:
206 $ cat /etc/pcp/labels/*
208 {
209 "tier": "production",
210 "datacenter": "hkg",
211 "services": ["indexer","database"]
212 }
213 Use pminfo to form the merged labelsets for several pmdasample(1) met‐
215 rics as follows:
216 $ pminfo -m -f --labels sample.rapid sample.colour sample.mirage
218 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 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 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 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
243 #!/usr/bin/env pmpython
244 import sys
246 from pcp import pmapi
247 import cpmapi as c_api
248 ctx = pmapi.pmContext(c_api.PM_CONTEXT_HOST, "local:")
250 for metric in sys.argv[1:]:
252 pmid = ctx.pmLookupName(metric)[0]
253 desc = ctx.pmLookupDescs(pmid)[0]
254 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 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
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 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 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 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 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 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 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
301 pmcd(1), PMAPI(3), pmFetch(3), pmGetInDom(3), pmLookupDesc(3),
302 pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3), pmNewCon‐
303 text(3) and labels.conf(5).
304Performance Co-Pilot PCP PMLOOKUPLABELS(3)