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

NAME

6       pmdaLabel,  pmdaSetLabelCallBack  -  fill  pmdaLabelSet structures with
7       metric labels
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/pmda.h>
12
13       int pmdaLabel(int ident, int type, pmLabelSet **sets, pmdaExt *pmda);
14       int pmdaSetLabelCallBack(pmdaInterface *dispatch,
15               pmdaLabelCallBack callback);
16
17       cc ... -lpcp_pmda -lpcp
18

DESCRIPTION

20       As  part  of  the  Performance Metrics Domain Agent (PMDA) API (see PM‐
21       DA(3)), pmdaLabel uses the standard PMDA(3) data structures  to  return
22       the labels for performance domain, instance domain, metric or individu‐
23       al instances in "JSONB" format in the given sets data structure.
24
25       The type argument determines the interpretation of ident  and  the  re‐
26       quested form of label, as follows:
27
28       PM_LABEL_DOMAIN
29           when ident is a PMDA domain identifier,
30
31       PM_LABEL_CLUSTER
32           when  ident  is a metric identifier and labels for the cluster con‐
33           taining that metric are being requested.
34
35       PM_LABEL_ITEM
36           when ident is a metric identifier,
37
38       PM_LABEL_INDOM
39           when ident is an instance domain identifier, or
40
41       PM_LABEL_INSTANCES
42           when ident is a metric identifier and labels for all  instances  of
43           that metric are being requested.
44
45       The  label  sets pointer must be initialised to NULL before calling pm‐
46       daLabel and space is only to be allocated when labels are  present  and
47       returned.   In  this  case, the return code must indicate the number of
48       label sets that have been allocated.  This will only  ever  be  greater
49       than one in the PM_LABEL_INSTANCES case.
50
51       This  is  one of the few generic callbacks in libpcp_pmda (see PMDA(3))
52       that is incomplete, requiring a further pmdaLabelCallBack method of its
53       own.   The additional callback should be registered using pmdaSetLabel‐
54       CallBack and the pmdaLabelCallBack method has the following prototype:
55       int func(pmInDom indom, unsigned int inst, pmLabelSet **set)
56
57       The purpose of the pmdaLabelCallBack routine is to return the  label(s)
58       for an individual instance inst of a given instance domain, indom.  Its
59       successful return code differs significantly to pmdaLabel, as described
60       below.
61

DIAGNOSTICS

63       On success pmdaLabel returns the number of label sets created.  This is
64       usually zero or one, except in the  case  of  PM_LABEL_INSTANCES  where
65       more  than one label sets will often be returned, one for each instance
66       of the requested metric.
67
68       By contrast, on success of the pmdaLabelCallBack routine the number  of
69       labels  successfully added to the provided labelset pointer must be re‐
70       turned (and not the total number of label sets).
71
72       If labels for the requested entity could not be obtained due to a cata‐
73       strophic  failure,  such  as an out of memory condition, these routines
74       will return a negative error code.
75

CAVEAT

77       The PMDA must be using PMDA_PROTOCOL_7 or later, as  specified  in  the
78       call to pmdaDSO(3) or pmdaDaemon(3).
79

SEE ALSO

81       pminfo(1), malloc(3), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3), pm‐
82       daInit(3) and pmLookupLabels(3).
83
84
85
86Performance Co-Pilot                  PCP                         PMDALABEL(3)
Impressum