# pmdalabel

## NAME



           **pmdaLabel** , **pmdaSetLabelCallBack** - fill pmLabelSet structures with
           metric labels
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
           **#include <pcp/pmda.h>**
    
           **int pmdaLabel(int** _ident_**, int** _type_**, pmLabelSet ****_sets_**,**
                         **pmdaExt ***_pmda_**);**
           **int pmdaSetLabelCallBack(pmdaInterface ***_dispatch_**,**
                                    **pmdaLabelCallBack** _callback_**);**
    
           **cc ... -lpcp_pmda -lpcp**
    


## DESCRIPTION



           As  part  of  the Performance Metrics Domain Agent (PMDA) API (see
           PMDA(3)), **pmdaLabel** uses the standard PMDA(3) data  structures  to
           return  the labels for performance domain, instance domain, metric
           or individual instances in "JSONB" format in the given  _sets_  data
           structure.
    
           The  _type_  argument determines the interpretation of _ident_ and the
           requested form of label, as follows:
    
           **PM_LABEL_DOMAIN**
               when _ident_ is a PMDA domain identifier,
    
           **PM_LABEL_CLUSTER**
               when _ident_ is a metric identifier and labels for the cluster
               containing that metric are being requested.
    
           **PM_LABEL_ITEM**
               when _ident_ is a metric identifier,
    
           **PM_LABEL_INDOM**
               when _ident_ is an instance domain identifier, or
    
           **PM_LABEL_INSTANCES**
               when _ident_ is a metric identifier and labels for all instances
               of that metric are being requested.
    
           The label _sets_ pointer must be initialised to NULL before calling
           **pmdaLabel** and space is only to be allocated when labels are
           present and returned.  In this case, the return code must indicate
           the number of label _sets_ that have been allocated.  This will only
           ever be greater than one in the **PM_LABEL_INSTANCES** case.
    
           This is one of the few generic callbacks in _libpcp_pmda_ (see
           PMDA(3)) that is incomplete, requiring a further **pmdaLabelCallBack**
           method of its own.  The additional callback should be registered
           using **pmdaSetLabelCallBack** and the **pmdaLabelCallBack** method has
           the following prototype:
           int func(pmInDom _indom_ , unsigned int _inst_ , pmLabelSet **_set_)
    
           The purpose of the **pmdaLabelCallBack** routine is to return the la‐
           bel(s) for an individual instance _inst_ of a given instance domain,
           _indom_.  Its successful return code differs significantly to **pmdaL‐**
           **abel** , as described below.
    


## CAVEAT



           The PMDA must be using **PMDA_INTERFACE_7** or later, as specified in
           the call to pmdaDSO(3) or pmdaDaemon(3).
    


## DIAGNOSTICS



           On success **pmdaLabel** returns the number of label _sets_ created.
           This is usually zero or one, except in the case of **PM_LABEL_IN‐**
           **STANCES** where more than one label _sets_ will often be returned, one
           for each instance of the requested metric.
    
           By contrast, on success of the **pmdaLabelCallBack** routine the num‐
           ber of labels successfully added to the provided labelset pointer
           must be returned (and not the total number of label _sets_).
    
           If labels for the requested entity could not be obtained due to a
           catastrophic failure, such as an out of memory condition, these
           routines will return a negative error code.
    


* * *