---
name: "pmmergelabels"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "4.3.2+really4.3.1-0.1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/pmMergeLabelSets"
---

# pmmergelabels(3)

merge sets of performance metric labels

Part of [pmMergeLabelSets(3)](/pmMergeLabelSets/3.md).

## 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)](/pmLookupLabels/3.md).

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)](/pmLookupLabels/3.md).

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)](/pminfo/1.md), [**PMAPI**(3)](/PMAPI/3.md) *and* [**pmLookupLabels**(3)](/pmLookupLabels/3.md).