pmmergelabels(3) — Linux manual page


PMMERGELABELS(3)        Library Functions Manual        PMMERGELABELS(3)

NAME         top

       pmMergeLabels, pmMergeLabelSets - merge sets of performance
       metric labels

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmMergeLabels(char **sets, int nsets, char *buffer, int

       int pmMergeLabelSets(pmLabelSet **sets, int nsets, char *buffer,
               int length, int (*filter)(const pmLabel *, const char *,
               void *), void *arg);

       cc ... -lpcp


       from pcp import pmapi

       buffer = pmapi.pmContext().pmMergeLabels(sets)
       buffer = pmapi.pmContext().pmMergeLabelSets(sets, filter)

DESCRIPTION         top

       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

       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

       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         top

       import sys
       import json
       from pcp import pmapi
       import cpmapi as c_api

       def merge_callback(label, jsondata, data=None):
           d = json.loads(jsondata)
           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))

DIAGNOSTICS         top

       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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2023-06-23.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-06-21.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot               PCP                  PMMERGELABELS(3)

Pages that refer to this page: pmlookuplabels(3)