HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |C SYNOPSIS |PYTHON SYNOPSIS |DESCRIPTION |LABEL SYNTAX |PRECEDENCE |DATA STRUCTURES |EXAMPLES |PYTHON EXAMPLE |DIAGNOSTICS |SEE ALSO |COLOPHON | |
PMLOOKUPLABELS(3) Library Functions ManualPMLOOKUPLABELS(3)pmLookupLabels,pmGetInstancesLabels,pmGetItemLabels,pmGetClusterLabels,pmGetInDomLabels,pmGetDomainLabels,pmGetContextLabels- retrieve labels associated with performance metric values
#include <pcp/pmapi.h>int pmLookupLabels(pmIDpmid, pmLabelSet **labelsets);int pmGetInstancesLabels(pmInDomindom, pmLabelSet **labelsets);int pmGetItemLabels(pmIDpmid, pmLabelSet **labelsets);int pmGetClusterLabels(pmIDpmid, pmLabelSet **labelsets);int pmGetInDomLabels(pmInDomindom, pmLabelSet **labelsets);int pmGetDomainLabels(intdomain, pmLabelSet **labelsets);int pmGetContextLabels(pmLabelSet **labelsets);cc ... -lpcp
from pcp import pmapilabelsets= pmapi.pmContext().pmLookupLabels(pmid)labelsets= pmapi.pmContext().pmGetInstancesLabels(indom)labelsets= pmapi.pmContext().pmGetItemLabels(pmid)labelsets= pmapi.pmContext().pmGetClusterLabels(pmid)labelsets= pmapi.pmContext().pmGetInDomLabels(indom)labelsets= pmapi.pmContext().pmGetDomainLabels(domain)labelsets= pmapi.pmContext().pmGetContextLabels()
Labels arename:value pairs associated with performance metric values for the purpose of attaching additional metric metadata to values. This metadata is less structured and exists separately to the metric descriptor available for every PCP metric frompmLookupDesc(3). Much like the metric descriptor metadata, labels are an integral part of the identity of each metric, and should rarely, if ever, change. ThepmLookupLabelsroutine is a convenience interface providing retrieval for all labels associated with a single performance met‐ ric identifier,pmid,exceptlabels at the instances level. La‐ bels at the instances level must be retrieved separately with a call topmGetInstancesLabelsbecause different metric instances may have labels with the same label name. ThepmLookupLabels function performs no caching of labels internally. For efficiency in communication and storage within the various components of the PMCS (Performance Metrics Collection System), labels are maintained using a hierarchy. The set of labels asso‐ ciated with any individual metric value consists of the union of labels from each of these sets of labels: 1. Global labels (apply to all metric values from a host or archive context)pmGetContextLabels provides thelabelsets associated with all metric values from a given source (PMAPI context). 2. Domain labels (apply to every metric within a PMDA)pmGetDomainLabels provides thelabelsets associated with thedomain identi‐ fier. 3. Instance Domain labels (apply to all metrics sharing that in‐ dom)pmGetInDomLabels provides thelabelsets associated with the instance domain identifierindom. 4. Cluster labels (apply to a group of metrics within one domain)pmGetClusterLabels provides thelabelsets associated with the metric cluster (domain,cluster) identified bypmid. 5. Item labels (apply to an individual performance metric)pmGetItemLabels provides thelabelsets associated with the metric item (domain,cluster,item) identified bypmid. 6. Instance labels (apply to individual instances of a metric)pmGetInstancesLabels provides the set of instance identifiers and labels inla‐belsets for each instance associated with the instance do‐ main identifierindom. The return value indicates the number of elements in the result - onelabelsets for each instance. These independentlabelsets can be merged usingpmMergeLabelSets(3) to form the complete set of all labels associ‐ ated with a given value. Note that the label sets returned bypmGetInstancesLabelscan be traversed but should not be merged be‐ cause the label names are unlikely to be unique for different in‐ stances of the givenindom.
Labels are stored and communicated within PCP using JSONB format. This format is a restricted form of JSON suitable for indexing and other operations. In JSONB form, insignificant whitespace is dis‐ carded, and the order of label names is not preserved. Within the PMCS a lexicographically sorted key space is always maintained, however. Duplicate label names are not permitted. The label with highest precedence is the only one presented. If duplicate names are presented at the same hierarchy level, only one will be pre‐ served (exactly which one wins is arbitrary, so do not rely on this). Allname:value pair(s) present will be converted to JSONB form and merged with the existing set of labels for the requested entity (context, domain, indom, metric or instance). The label names are further constrained to the same set of rules defined forPMNSsubtree names. Each component in a labelname must begin with an alphabetic char‐ acter, and be followed by zero or more characters drawn from the alphabetics, the digits and the underscore (``_'') character. For alphabetic characters in aname, upper and lower case are distin‐ guished. Thevalue of a label offers significantly more freedom, and may be any valid value as defined by the JSON (https://www.json.org) specification. Redundant whitespace is always removed within the PMCS.
The complete set of labels associated with any metric value is built from several sources and duplicate label names may exist at any point in the source hierarchy. However, when evaluating the label set (merging labels from the different sources) the JSONB concept of only presenting unique labels is used. It is therefore important to define precedence rules in order that a deterministic set of uniquely named labels can be defined. As a rule of thumb, the labels closest to PMNS leaf nodes and met‐ ric values take precedence: 1. Global context labels (as reported by thepmcd.labels metric) are the lowest prece‐ dence. 2. Domain labels (for all metrics and instances from a PMDA) are the next high‐ est precedence. 3. Instance Domain labels associated with an InDom are the next highest precedence. 4. Metric cluster labels associated with a PMID cluster are the next highest prece‐ dence. 5. Metric item labels associated with an individual PMID are the next highest prece‐ dence. 6. Instance labels associated with a metric instance identifier have highest precedence.
The primary output frompmLookupLabelsis returned in the argumentlabelsets as an array, using the following component data struc‐ tures; struct { uint name : 16; /* label name offset in JSONB string */ uint namelen : 8; /* length of name excluding the null */ uint flags : 8; /* information about this label */ uint value : 16; /* offset of the label value */ uint valuelen : 16; /* length of value in bytes */ } pmLabel; struct { uint inst; /* PM_IN_NULL or the instance ID */ int nlabels; /* count of labels or error code */ char *json; /* JSON formatted labels string */ uint jsonlen : 16; /* JSON string length byte count */ uint padding : 16; /* zero, reserved for future use */ pmLabel *labels; /* indexing into the JSON string */ } pmLabelSet; ThepmLabel provides information about an individual label. This includes the offsets to the start of itsname andvalue in thejson string of apmLabelSet, their respective lengths, and also any informative flags associated with the label (describing where it lies in the hierarchy of labels, and whether it is an intrinsic or extrinsic label). Building on this, thepmLabelSet provides information about the set of labels associated with an entity (context, domain, indom, metric cluster, item or instance). The entity will be from any one level of the label hierarchy. If at the lowest hierarchy lev‐ el (which happens to be highest precedence - PM_LABEL_INSTANCES) then theinst field will contain an actual instance identifier in‐ stead of PM_IN_NULL. Thenlabels field describes the number of labels (name:value pairs) that can be found in both the accompanyingjson string (which is JSONB format - no unnecessary whitespace and with no du‐ plicate label names) and the accompanyinglabels array (which hasnlabels elements). Consider a deployment with global labels (assume $PCP_SYSCONF_DIR is set to its usual location of/etc/pcp) as follows:$ cat /etc/pcp/labels/* { "tier": "production", "datacenter": "hkg", "services": ["indexer","database"] } Usepminfoto form the mergedlabelsets for severalpmdasample(1) metrics as follows:$ pminfo -m -f --labels sample.rapid sample.colour sample.mirage sample.rapid PMID: 30.0.64 value 800000000 labels {"agent":"sample","datacenter":"sydney","hostname":"acme.com","measure":"speed","role":"testing","services":["indexer","database"],"tier":"production","units":"metres per second","unitsystem":"SI"} sample.colour PMID: 30.0.5 inst [0 or "red"] value 101 inst [1 or "green"] value 202 inst [2 or "blue"] value 303 inst [0 or "red"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"} inst [1 or "green"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"} inst [2 or "blue"] labels {"agent":"sample","datacenter":"syd","hostname":"acme.com","model":"RGB","role":"testing","services":["indexer","database"],"tier":"production"} sample.mirage PMID: 29.0.37 inst [0 or "m-00"] value 99 inst [0 or "m-00"] labels {"agent":"sample","datacenter":"sydney","hostname":"acme.com","role":"testing","services":["indexer","database"],"tier":"production","transient":false} Here,pminfohas merged the separate sets of labels returned frompmGetContextLabels(names: datacenter, hostname, services, tier),pmGetDomainLabels(names: role, agent),pmGetInDomLabels(names: model),pmGetItemLabels(names: units, unitsystem) andpmGetInstancesLabels(names: transient) to form the complete set for each of the metrics.#!/usr/bin/env pmpythonimport sysfrom pcp import pmapiimport cpmapi as c_apictx = pmapi.pmContext(c_api.PM_CONTEXT_HOST, "local:")for metric in sys.argv[1:]:pmid = ctx.pmLookupName(metric)[0]desc = ctx.pmLookupDescs(pmid)[0]print("== label sets for %s ==" % metric)labelSetList = ctx.pmLookupLabels(pmid)# class pmLabelSet has a __str__ handlerfor labelSet in labelSetList:print("%s" % labelSet)ctx.pmFreeLabelSets(labelSetList)if desc.contents.indom != c_api.PM_INDOM_NULL:print("== instances label sets for %s ==" % metric)labelSetList = ctx.pmGetInstancesLabels(desc.contents.indom)for labelSet in labelSetList:print("%s" % labelSet)ctx.pmFreeLabelSets(labelSetList)On success these interfaces all return the number of elements in thelabelsets array. associated with performance metrics. The memory associated withlabelsets should be released usingpmFreeLabelSets(3) when no longer needed. Only in the case ofpmLookupLabelswill the resultinglabelsets be a merged set of labels from all hierarchy levels (except at the instances level, as described above). For the other routines, except forpmGetInstancesLabels, if no la‐ bels exist at all for the requested hierarchy level the return code will be zero and no space will have been allocated. In the case ofpmGetInstancesLabels, which can return multiple el‐ ements in itslabelsets result (one set of labels for each in‐ stance), thenlabels field may be either zero indicating no labels for that instance, or a positive count of labels, or a negative PMAPI error code. Note that it is mandatory for a call topmGetInstancesLabelsto be preceded by a call topmGetInDom(3) to ensure the instances have been resolved within the PMDA. If no result can be obtained, e.g. due to IPC failure using the current PMAPI context thenpmGetInstancesLabelswill return a neg‐ ative error code which may be examined using A successful return from the Python API always provides thela‐belsets result in the form of a list, for all labels functions. On error apmErrexception is raised containing the error code and diagnostic.pmErrStr(3).
pmcd(1),PMAPI(3),pmFetch(3),pmGetInDom(3),pmLookupDesc(3),pmLookupName(3),pmFreeLabelSets(3),pmMergeLabelSets(3),pmNewContext(3) andlabels.conf(5).
This page is part of thePCP (Performance Co-Pilot) project. In‐ formation about the project can be found at ⟨http://www.pcp.io/⟩. If you have a bug report for this manual page, send it to pcp@groups.io. This page was obtained from the project's upstream Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgPerformance Co-Pilot PCPPMLOOKUPLABELS(3)Pages that refer to this page:pcp-geolocate(1), pmdaopenmetrics(1), pminfo(1), pmlogdump(1), pmseries(1), pmapi(3), pmdalabel(3), pmfetch(3), pmfreelabelsets(3), pmlookupindomtext(3), pmlookuptext(3), pmmergelabels(3), pmprintlabelsets(3), pmsetmode(3), pmwebapi(3), labels.conf(5), LOGARCHIVE(5)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |