# pmlookuplabels

## NAME



           **pmLookupLabels** , **pmGetInstancesLabels** , **pmGetItemLabels** ,
           **pmGetClusterLabels** , **pmGetInDomLabels** , **pmGetDomainLabels** ,
           **pmGetContextLabels** - retrieve labels associated with performance
           metric values
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmLookupLabels(pmID** _pmid_**, pmLabelSet ****_labelsets_**);**
    
           **int pmGetInstancesLabels(pmInDom** _indom_**, pmLabelSet ****_labelsets_**);**
           **int pmGetItemLabels(pmID** _pmid_**, pmLabelSet ****_labelsets_**);**
           **int pmGetClusterLabels(pmID** _pmid_**, pmLabelSet ****_labelsets_**);**
           **int pmGetInDomLabels(pmInDom** _indom_**, pmLabelSet ****_labelsets_**);**
           **int pmGetDomainLabels(int** _domain_**, pmLabelSet ****_labelsets_**);**
           **int pmGetContextLabels(pmLabelSet ****_labelsets_**);**
    
           **cc ... -lpcp**
    


## PYTHON SYNOPSIS



           **from pcp import pmapi**
    
           _labelsets_ **= 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()**
    


## DESCRIPTION



           Labels  are  _name_ :_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  from
           pmLookupDesc(3).
    
           Much like the metric descriptor metadata, labels are  an  integral
           part  of  the identity of each metric, and should rarely, if ever,
           change.
    
           The **pmLookupLabels** routine is a  convenience  interface  providing
           retrieval for all labels associated with a single performance met‐
           ric  identifier,  _pmid_ , **except** labels at the instances level.  La‐
           bels at the instances level must be retrieved  separately  with  a
           call  to  **pmGetInstancesLabels** because different metric instances
           may have labels with the  same  label  name.   The  **pmLookupLabels**
           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 the _labelsets_ associated with all metric values
                   from a given source (PMAPI context).
    
           2. Domain labels (apply to every metric within a PMDA)
    
           **pmGetDomainLabels**
                   provides the _labelsets_ associated with the _domain_ identi‐
                   fier.
    
           3. Instance Domain labels (apply to all metrics sharing that in‐
           dom)
    
           **pmGetInDomLabels**
                   provides the _labelsets_ associated with the instance domain
                   identifier _indom_.
    
           4. Cluster labels (apply to a group of metrics within one domain)
    
           **pmGetClusterLabels**
                   provides the _labelsets_ associated with the metric cluster
                   (domain,cluster) identified by _pmid_.
    
           5. Item labels (apply to an individual performance metric)
    
           **pmGetItemLabels**
                   provides the _labelsets_ associated with the metric item
                   (domain,cluster,item) identified by _pmid_.
    
           6. Instance labels (apply to individual instances of a metric)
    
           **pmGetInstancesLabels**
                   provides the set of instance identifiers and labels in _la‐_
                   _belsets_ for each instance associated with the instance do‐
                   main identifier _indom_.  The return value indicates the
                   number of elements in the result - one _labelsets_ for each
                   instance.
    
           These independent _labelsets_ can be merged using
           pmMergeLabelSets(3) to form the complete set of all labels associ‐
           ated with a given value.  Note that the label sets returned by
           **pmGetInstancesLabels** can be traversed but should not be merged be‐
           cause the label names are unlikely to be unique for different in‐
           stances of the given _indom_.
    


## LABEL SYNTAX



           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).
    
           All _name_ :_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 for **PMNS** subtree names.
    
           Each component in a label _name_ 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 a _name_ , upper and lower case are distin‐
           guished.
    
           The _value_ 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.
    


## PRECEDENCE



           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 the _pmcd.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.
    


## DATA STRUCTURES



           The primary output from **pmLookupLabels** is returned in the argument
           _labelsets_ 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;
    
           The _pmLabel_ provides information about an individual label.  This
           includes the offsets to the start of its _name_ and _value_ in the
           _json_ string of a _pmLabelSet_ , 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, the _pmLabelSet_ 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 the _inst_ field will contain an actual instance identifier in‐
           stead of PM_IN_NULL.
    
           The _nlabels_ field describes the number of labels (name:value
           pairs) that can be found in both the accompanying _json_ string
           (which is JSONB format - no unnecessary whitespace and with no du‐
           plicate label names) and the accompanying _labels_ array (which has
           _nlabels_ elements).
    


## EXAMPLES



           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"]
           }
    
           Use **pminfo** to form the merged _labelsets_ for several pmdasample(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, **pminfo** has merged the separate sets of labels returned from
           **pmGetContextLabels**(_name_ s: datacenter, hostname, services, tier),
           **pmGetDomainLabels**(_name_ s: role, agent), **pmGetInDomLabels**(_name_ s:
           model), **pmGetItemLabels**(_name_ s: units, unitsystem) and
           **pmGetInstancesLabels**(_name_ s: transient) to form the complete set
           for each of the metrics.
    


## PYTHON EXAMPLE



           **#!/usr/bin/env pmpython**
    
           **import sys**
           **from pcp import pmapi**
           **import cpmapi as c_api**
    
           **ctx = 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__ handler**
               **for 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)**
    


## DIAGNOSTICS



           On success these interfaces all return the number of elements in
           the _labelsets_ array.  associated with performance metrics.  The
           memory associated with _labelsets_ should be released using
           pmFreeLabelSets(3) when no longer needed.
    
           Only in the case of **pmLookupLabels** will the resulting _labelsets_ be
           a merged set of labels from all hierarchy levels (except at the
           instances level, as described above).
    
           For the other routines, except for **pmGetInstancesLabels** , 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 of **pmGetInstancesLabels** , which can return multiple el‐
           ements in its _labelsets_ result (one set of labels for each in‐
           stance), the _nlabels_ 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 to **pmGetInstancesLabels** to be
           preceded by a call to pmGetInDom(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 then **pmGetInstancesLabels** will return a neg‐
           ative error code which may be examined using
    
           A successful return from the Python API always provides the _la‐_
           _belsets_ result in the form of a list, for all labels functions.
           On error a **pmErr** exception is raised containing the error code and
           diagnostic.  pmErrStr(3).
    


* * *