1PMMERGELABELS(3)           Library Functions Manual           PMMERGELABELS(3)
2
3
4

NAME

6       pmMergeLabels,  pmMergeLabelSets  -  merge  sets  of performance metric
7       labels
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmMergeLabels(char **sets, int nsets, char *buffer, int length);
13
14       int pmMergeLabelSets(pmLabelSet **sets, int nsets, char *buffer, int
15               length, int (*filter)(const pmLabel *, const char *, void *),
16               void *arg);
17
18       cc ... -lpcp
19

DESCRIPTION

21       pmMergeLabels takes multiple (nsets) performance metric label sets  and
22       merges  them into a single result buffer of length bytes.  Both the in‐
23       put sets and the result buffer are name:value pairs in the "JSONB" for‐
24       mat described on pmLookupLabels(3).
25
26       The  pmMergeLabelSets interface serves the same purpose, but allows for
27       indexed sets of labels to be merged.  The format of the pmLabelSet data
28       structure is described in detail in pmLookupLabels(3).
29
30       Although  names  may  repeat  across the provided label sets, duplicate
31       names are not allowed in the final buffer.  Any label names occuring in
32       more  than  one  of  the  input label sets are reduced to one using the
33       rules described in the "PRECEDENCE" section of pmLookupLabels.  The po‐
34       sition of each element in the sets array is significant in terms of the
35       precedence rules - earlier positions are taken to be  of  lower  prece‐
36       dence to later positions.
37
38       Values must be primitive JSON entities (e.g. numbers, strings), one-di‐
39       mensional arrays or maps (i.e. simple associative arrays).
40
41       In addition to using indexed label sets the pmMergeLabelSets  interface
42       provides an optional filter callback function.  If non-NULL, this func‐
43       tion will be called for each label that would be added  to  the  output
44       buffer, allowing finer-grained control over the final merged set.  This
45       mechanism can be used to filter individual labels based on their  name,
46       value, and/or flags.  If the filter function returns zero (false), then
47       the given label is filtered from the resulting set.  Any  non-zero  re‐
48       turn value indicates that the label should be included in the buffer.
49

DIAGNOSTICS

51       On  success, both pmMergeLabels and pmMergeLabelSets returns the number
52       of bytes written into the supplied buffer.
53
54       Failure to parse the input strings, failure to allocate memory, or  any
55       internal inconsistencies found will result in a negative return code.
56

SEE ALSO

58       pminfo(1), PMAPI(3) and pmLookupLabels(3).
59
60
61
62Performance Co-Pilot                  PCP                     PMMERGELABELS(3)
Impressum