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

CAVEAT

63       The  PMDA  must  be using PMDA_PROTOCOL_7 or later, as specified in the
64       call to pmdaDSO(3) or pmdaDaemon(3).
65

DIAGNOSTICS

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