PMMERGELABELS(3)

💖 pmMergeLabels — bestie edition 💖

okay so this is the manual for pmMergeLabels and pmMergeLabelSets, which live in the Library Functions Manual (section 3, if u were wondering 🎀). they merge sets of performance metric labels. that's the whole vibe. let's get into it ✨

---

🌸 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 ✨

so pmMergeLabels takes multiple label sets (there are nsets of them, bestie) and merges them all into one single result buffer that's length bytes long. both the input sets AND the result buffer are name:value pairs in the "JSONB" format that's described over on pmLookupLabels(3). 💖

the pmMergeLabelSets interface does the exact same thing, but it lets u merge indexed sets of labels. the format of the pmLabelSet data structure is described in detail in pmLookupLabels(3). go read that one, i'll wait 🫶

okay so here's the thing — names can repeat across the label sets u hand in, but duplicate names are NOT allowed in the final buffer. periodt. so any label name that shows up in more than one input set gets reduced down to one, using the rules in the "PRECEDENCE" section of pmLookupLabels. and listen: the position of each element in the sets array matters for those precedence rules — earlier positions are taken to be of lower precedence than later positions. so like, order is the moment, fr fr 👑

values have to be primitive JSON entities (numbers, strings, that kind of thing), one-dimensional arrays, or maps (aka simple associative arrays). no fancy business 💅

and here's the extra lil bonus: besides using indexed label sets, the pmMergeLabelSets interface also gives u an optional filter callback function. if it's non-NULL, this function gets called for every label that would be added to the output buffer, which gives u finer-grained control over the final merged set. u can use this to filter individual labels based on their name, value, and/or flags. if the filter function returns zero (false), then that label gets filtered out of the resulting set. any non-zero return value means the label should be included in the buffer. simple as 🌈

---

🎀 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 return the number of bytes written into the supplied buffer. slay 💅

but if it fails to parse the input strings, fails to allocate memory, or finds any internal inconsistencies, ur getting a negative return code. so like, check that return value bestie, don't just vibe past it 💀

---

🔥 SEE ALSO 🔥

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

---

and that's the whole page!! this one came to u from Performance Co-Pilot (that's the PCP girlies 🌸), and it's the PMMERGELABELS(3) page — no cap, go merge some labels, u got this 👑💖