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

PYTHON SYNOPSIS

21       from pcp import pmapi
22
23       buffer = pmapi.pmContext().pmMergeLabels(sets)
24       buffer = pmapi.pmContext().pmMergeLabelSets(sets, filter)
25
26

DESCRIPTION

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

PYTHON EXAMPLE

58       import sys
59       import json
60       from pcp import pmapi
61       import cpmapi as c_api
62
63       def merge_callback(label, jsondata, data=None):
64           d = json.loads(jsondata)
65           labelsD.update(d)
66           return 0
67
68       ctx = pmapi.pmContext()
69
70       for metric in sys.argv[1:]:
71           pmid = ctx.pmLookupName(metric)[0]
72           lset = ctx.pmLookupLabels(pmid)
73           labelsD = {}
74           ctx.pmMergeLabelSets(lset, merge_callback)
75           print("== %s ===" % metric)
76           for n,v in labelsD.items():
77               print("    %s = %s" % (n,v))
78           ctx.pmFreeLabelSets(lset)
79

DIAGNOSTICS

81       On  success, both pmMergeLabels and pmMergeLabelSets returns the number
82       of bytes written into the supplied buffer.
83
84       Failure to parse the input strings, failure to allocate memory, or  any
85       internal inconsistencies found will result in a negative return code.
86

SEE ALSO

88       pminfo(1), PMAPI(3) and pmLookupLabels(3).
89
90
91
92Performance Co-Pilot                  PCP                     PMMERGELABELS(3)
Impressum