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 occurring 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 prece‐
       dence to later positions.

       Values must be primitive JSON entities (e.g. numbers, strings), one-dimensional arrays or maps (i.e. sim‐
       ple associative arrays).

       In  addition to using indexed label sets the pmMergeLabelSets interface provides an optional filter call‐
       back function.  If non-NULL, this function will be called for each label that would be added to the  out‐
       put buffer, allowing finer-grained control over the final merged set.  This mechanism can be used to fil‐
       ter  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).

Performance Co-Pilot                                   PCP                                      PMMERGELABELS(3)