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. It performs no caching of labels internally.
49 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 1. Global labels (apply to all metric values from a host or archive
57 context)
58 pmGetContextLabels
60 provides the labelset associated with all metric values from a
61 given source (PMAPI context).
62 2. Domain labels (apply to every metric within a PMDA)
64 pmGetDomainLabels
66 provides the labelset associated with the domain identifier.
67 3. Instance Domain labels (apply to all metrics sharing that indom)
69 pmGetInDomLabels
71 provides the labelset associated with the instance domain iden‐
72 tifier indom.
73 4. Cluster labels (apply to a group of metrics within one domain)
75 pmGetClusterLabels
77 provides the labelset associated with the metric cluster
78 (domain,cluster) identified by pmid.
79 5. Item labels (apply to an individual performance metric)
81 pmGetItemLabels
83 provides the labelset associated with the metric item
84 (domain,cluster,item) identified by pmid.
85 6. Instance labels (apply to individual instances of a metric)
87 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 These independent labelsets can be merged using pmMergeLabelSets(3) to
95 form the complete set of all labels associated with a given value.
96
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 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 The label names are further constrained to the same set of rules
113 defined for PMNS subtree names.
114 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 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
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 As a rule of thumb, the labels closest to PMNS leaf nodes and metric
134 values take precedence:
135 1. Global context labels
137 (as reported by the pmcd.labels metric) are the lowest precedence.
138 2. Domain labels
140 (for all metrics and instances from a PMDA) are the next highest
141 precedence.
142 3. Instance Domain labels
144 associated with an InDom are the next highest precedence.
145 4. Metric cluster labels
147 associated with a PMID cluster are the next highest precedence.
148 5. Metric item labels
150 associated with an individual PMID are the next highest precedence.
151 6. Instance labels
153 associated with a metric instance identifier have highest prece‐
154 dence.
155
157 The primary output from pmLookupLabels is returned in the argument
158 labelset as an array, using the following component data structures;
159 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 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 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 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 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
197 Consider a deployment with global labels (assume $PCP_SYSCONF_DIR is
198 set to its usual location of /etc/pcp) as follows:
199 $ cat /etc/pcp/labels/*
201 {
202 "tier": "production",
203 "datacenter": "hkg",
204 "services": ["indexer","database"]
205 }
206 Use pminfo to form the merged labelsets for several pmdasample(1) met‐
208 rics as follows:
209 $ pminfo -m -f --labels sample.rapid sample.colour sample.mirage
211 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 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 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 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
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 Only in the case of pmLookupLabels will the resulting labelset be a
242 merged set of labels from all hierarchy levels.
243 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 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 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 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 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
266 pmcd(1), PMAPI(3), pmFetch(3), pmGetInDom(3), pmLookupDesc(3),
267 pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3) and pmNewCon‐
268 text(3).
269Performance Co-Pilot PCP PMLOOKUPLABELS(3)