# pmmergelabels

## NAME



           **pmMergeLabels** , **pmMergeLabelSets** - merge sets of performance metric
           labels
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmMergeLabels(char ****_sets_**, int** _nsets_**, char ***_buffer_**,**
                             **int** _length_**);**
    
           **int pmMergeLabelSets(pmLabelSet ****_sets_**, int** _nsets_**, char ***_buffer_**,**
                                **int** _length_**,**
                                **int (***_filter_**)(const pmLabel *, const char *, void *),**
                                **void ***_arg_**);**
    
           **cc ... -lpcp**
    


## PYTHON SYNOPSIS



           **from pcp import pmapi**
    
           _buffer_ = pmapi.pmContext().pmMergeLabels(_sets_)
           _buffer_ = pmapi.pmContext().pmMergeLabelSets(_sets_ , _filter_)
    


## DESCRIPTION



           **pmMergeLabels** takes multiple (_nsets_) performance metric label _sets_
           and merges them into a single result _buffer_ of _length_ bytes.  Both
           the  input  _sets_ and the result _buffer_ are _name_ :_value_ pairs in the
           "JSONB" format described on pmLookupLabels(3).
    
           The **pmMergeLabelSets** interface serves the same purpose, but allows
           for indexed _sets_ of labels to be merged.  The format of the  _pmLa‐_
           _belSet_ data structure is described in detail in pmLookupLabels(3).
    
           Although  names  may repeat across the provided label _sets_ , dupli‐
           cate names are not allowed in the final _buffer_.  Any  label  names
           occurring  in more than one of the input label _sets_ are reduced to
           one using the rules described in the "PRECEDENCE" section  of  **pm‐**
           **LookupLabels**.   The  position of each element in the _sets_ array is
           significant in terms of the precedence rules -  earlier  positions
           are taken to be of lower precedence to later positions.
    
           Values  must  be  primitive JSON entities (e.g. numbers, strings),
           one-dimensional arrays or maps (i.e. simple associative arrays).
    
           In addition to using indexed label _sets_ the  **pmMergeLabelSets** in‐
           terface  provides  an  optional _filter_ callback function.  If non-
           NULL, this function will be called for each label  that  would  be
           added  to  the  output _buffer_ , allowing finer-grained control over
           the final merged set.  This mechanism can be used to _filter_  indi‐
           vidual  labels  based  on their name, value, and/or flags.  If the
           _filter_ function returns zero (false), then the given label is fil‐
           tered from the resulting set.  Any non-zero return value indicates
           that the label should be included in the _buffer_.
    


## PYTHON EXAMPLE



           **import sys**
           **import json**
           **from pcp import pmapi**
           **import cpmapi as c_api**
    
           **def merge_callback(label, jsondata, data=None):**
               **d = json.loads(jsondata)**
               **labelsD.update(d)**
               **return 0**
    
           **ctx = pmapi.pmContext()**
    
           **for metric in sys.argv[1:]:**
               **pmid = ctx.pmLookupName(metric)[0]**
               **lset = ctx.pmLookupLabels(pmid)**
               **labelsD = {}**
               **ctx.pmMergeLabelSets(lset, merge_callback)**
               **print("== %s ===" % metric)**
               **for n,v in labelsD.items():**
                   **print("    %s = %s" % (n,v))**
               **ctx.pmFreeLabelSets(lset)**
    


## DIAGNOSTICS



           On success, both **pmMergeLabels** and  **pmMergeLabelSets** returns  the
           number of bytes written into the supplied _buffer_.
    
           Failure to parse the input strings, failure to allocate memory, or
           any  internal  inconsistencies found will result in a negative re‐
           turn code.
    


* * *