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 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 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 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 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 1. Global labels (apply to all metric values from a host or archive
44 context)
45 pmGetContextLabels
47 provides the labelset associated with all metric values from a
48 given source (PMAPI context).
49 2. Domain labels (apply to every metric within a PMDA)
51 pmGetDomainLabels
53 provides the labelset associated with the domain identifier.
54 3. Instance Domain labels (apply to all metrics sharing that indom)
56 pmGetInDomLabels
58 provides the labelset associated with the instance domain iden‐
59 tifier indom.
60 4. Cluster labels (apply to a group of metrics within one domain)
62 pmGetClusterLabels
64 provides the labelset associated with the metric cluster
65 (domain,cluster) identified by pmid.
66 5. Item labels (apply to an individual performance metric)
68 pmGetItemLabels
70 provides the labelset associated with the metric item
71 (domain,cluster,item) identified by pmid.
72 6. Instance labels (apply to individual instances of a metric)
74 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 These independent labelsets can be merged using pmMergeLabelSets(3) to
82 form the complete set of all labels associated with a given value.
83
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 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 The label names are further constrained to the same set of rules
100 defined for PMNS subtree names.
101 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 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
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 As a rule of thumb, the labels closest to PMNS leaf nodes and metric
121 values take precedence:
122 1. Global context labels
124 (as reported by the pmcd.labels metric) are the lowest precedence.
125 2. Domain labels
127 (for all metrics and instances from a PMDA) are the next highest
128 precedence.
129 3. Instance Domain labels
131 associated with an InDom are the next highest precedence.
132 4. Metric cluster labels
134 associated with a PMID cluster are the next highest precedence.
135 5. Metric item labels
137 associated with an individual PMID are the next highest precedence.
138 6. Instance labels
140 associated with a metric instance identifier have highest prece‐
141 dence.
142
144 The primary output from pmLookupLabels is returned in the argument
145 labelset as an array, using the following component data structures;
146 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 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 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 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 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
184 Consider a deployment with global labels (assume $PCP_SYSCONF_DIR is
185 set to its usual location of /etc/pcp) as follows:
186 $ cat /etc/pcp/labels/*
188 {
189 "tier": "production",
190 "datacenter": "hkg",
191 "services": ["indexer","database"]
192 }
193 Use pminfo to form the merged labelsets for several pmdasample(1) met‐
195 rics as follows:
196 $ pminfo -m -f --labels sample.rapid sample.colour sample.mirage
198 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 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 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 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
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 Only in the case of pmLookupLabels will the resulting labelset be a
229 merged set of labels from all hierarchy levels.
230 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 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 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 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
249 pmcd(1), PMAPI(3), pmFetch(3), pmGetInDom(3), pmLookupDesc(3),
250 pmLookupName(3), pmFreeLabelSets(3), pmMergeLabelSets(3) and pmNewCon‐
251 text(3).
252Performance Co-Pilot PCP PMLOOKUPLABELS(3)