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 pmLabelSet data structure is described in detail
       in pmLookupLabels(3).

       Although names may repeat across the provided label sets, duplicate names are not  allowed
       in  the  final  buffer.  Any label names occuring in more than one of the input label sets
       are  reduced  to  one  using  the  rules  described  in  the   "PRECEDENCE"   section   of
       pmLookupLabels.  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  interface  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 individual labels based on their
       name, value, and/or flags.  If the filter function returns zero (false),  then  the  given
       label  is  filtered  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 return code.

SEE ALSO

       pminfo(1), PMAPI(3) and pmLookupLabels(3).