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

NAME

6       pmdaInit, pmdaRehash, pmdaSetFlags, pmdaSetCommFlags, pmdaExtSetFlags -
7       initialize a PMDA
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/pmda.h>
12
13       void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms, int nindoms,
14               pmdaMetric *metrics, int nmetrics);
15       void pmdaRehash(pmdaExt *pmda, pmdaMetric *metrics, int nmetrics);
16       void pmdaSetFlags(pmdaInterface *dispatch, int flags);
17       void pmdaSetCommFlags(pmdaInterface *dispatch, int flags);
18       void pmdaExtSetFlags(pmdaExt *pmda, int flags);
19
20       cc ... -lpcp_pmda -lpcp
21

DESCRIPTION

23       pmdaInit  initializes  a  PMDA so that it is ready to receive PDUs from
24       pmcd(1).  The function expects as arguments the instance  domain  table
25       (indoms)  and  the metric description table (metrics) that are initial‐
26       ized by the PMDA. The arguments nindoms and nmetrics should be  set  to
27       the number of instances and metrics in the tables, respectively.
28
29       Much  of  the  pmdaInterface structure can be automatically initialized
30       with pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3).   pmdaInit  completes
31       the  PMDA initialization phase with three operations.  The first opera‐
32       tion adds the domain and instance numbers to the  instance  and  metric
33       tables.   Singular  metrics (metrics without an instance domain) should
34       have the instance domain PM_INDOM_NULL set in the indom  field  of  the
35       pmDesc  structure  (see pmLookupDesc(3)).  Metrics with an instance do‐
36       main should set this field to be the serial number of the instance  do‐
37       main in the indoms table.
38
39       The  instance  domain table may be made empty by setting indoms to NULL
40       and nindoms to 0.  This allows the caller to provide custom  Fetch  and
41       Instance  callback  functions.   The  metric table may be made empty by
42       setting metrics to NULL and nmetrics to 0.  This allows the  caller  to
43       provide custom Fetch and Descriptor callback functions.
44

EXAMPLE

46       For example, a PMDA has three metrics: A, B and C, and two instance do‐
47       mains X and Y, with two instances in each  instance  domain.   The  in‐
48       stance domain and metrics description tables could be defined as:
49
50            static pmdaInstid _X[] = {
51                { 0, "X1" }, { 1, "X2" }
52            };
53
54            static pmdaInstid _Y[] = {
55                { 0, "Y1" }, { 1, "Y2" }
56            };
57
58            static pmdaIndom indomtab[] = {
59            #define X_INDOM 0
60                { X_INDOM, 2, _X },
61            #define Y_INDOM 3
62                { Y_INDOM, 2, _Y }
63            };
64
65            static pmdaMetric metrictab[] = {
66            /* A */
67                { (void *)0,
68                  { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
69                    { 0,0,0,0,0,0} }, },
70            /* B */
71                { (void *)0,
72                  { PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
73                    { 0,0,0,0,0,0} }, },
74            /* C */
75                { (void *)0,
76                  { PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
77                    { 0,1,0,0,PM_TIME_SEC,0} }, }
78            };
79
80       The  metric description table defines metric A with no instance domain,
81       metric B with instance domain X and metric C with  instance  domain  Y.
82       Metric  C  has  units of seconds, while the other metrics have no units
83       (simple counters).  pmdaInit will take these structures and assign  the
84       PMDA(3)  domain  number  to the it_indom field of each instance domain.
85       This identifier also replaces the indom field of all metrics which have
86       that instance domain, so that they are correctly associated.
87
88       The  second  stage  opens the help text file, if one was specified with
89       the -h command line option (see pmdaGetOpt(3)) or as a  helptext  argu‐
90       ment to pmdaDSO(3) or pmdaDaemon(3).
91
92       The final stage involves preparing the metric table lookup strategy.
93

METRIC LOOKUP

95       When fetch and descriptor requests are made of the PMDA, each requested
96       PMID must be mapped to a metric table entry.  There are currently three
97       strategies  for  performing  this  mapping - direct, linear and hashed.
98       Each has its own set of tradeoffs and an appropriate strategy should be
99       selected for each PMDA.
100
101       If  all  of  the metric PMID item numbers correspond to the position in
102       the metrics table, then direct mapping is used.  This is the most effi‐
103       cient  of  the lookup functions as it involves a direct array index (no
104       additional memory is required nor any additional processing  overhead).
105       If  the  PMID  numbering  requirement  is met by the PMDA, it is ideal.
106       This strategy can be explicitly requested by calling pmdaSetFlags(pmda,
107       PMDA_EXT_FLAG_DIRECT)  before  calling  pmdaInit.  In this case, if the
108       direct mapping is not possible (e.g. due to an oversight on the part of
109       the  PMDA  developer),  a  warning is logged and the linear strategy is
110       used instead.
111
112       The second strategy (linear search) is the default, when a direct  map‐
113       ping  cannot  be established.  This provides greater flexibility in the
114       PMID numbering scheme, as the PMDA item  numbers  do  not  have  to  be
115       unique  (hence, the PMID cluster numbers can be used more freely, which
116       is often extremely convenient for the PMDA developer).  However, lookup
117       involves  a  linear  walk  from  the  start of the metric table until a
118       matching PMID is found, for each requested PMID in a request.
119
120       The third strategy (hash lookup) can be requested by  calling  pmdaSet‐
121       Flags(pmda, PMDA_EXT_FLAG_HASHED) before calling pmdaInit.  This strat‐
122       egy is most useful for PMDAs with large numbers of metrics  (many  hun‐
123       dreds,  or  thousands).   Such PMDAs will almost always use the cluster
124       numbering scheme, so the direct lookup  scheme  becomes  inappropriate.
125       They  may  also  be  prepared to sacrifice a small amount of additional
126       memory for a hash table, mapping PMID to metric table offsets, to speed
127       up lookups in their vast metric tables.
128
129       This  final  strategy  can also be used by PMDAs serving up dynamically
130       numbered metrics.  For this case, the  pmdaRehash  function  should  be
131       used  to replace the metric table when new metrics become available, or
132       existing metrics are removed.  The PMID hash mapping will be recomputed
133       at the same time that the new metric table is installed.
134

METRIC CHANGES

136       It  should  be well understood by PMDA authors that metric metadata for
137       individual metrics is fixed, and ideally would not ever change.  In the
138       situation where metadata is incorrect and is updated, such a change re‐
139       quires correction to logged metrics using pmlogrewrite(1), and as a re‐
140       sult should be avoided whenever possible.
141
142       However,  a PMDA may become aware of new domain metrics at runtime, and
143       in this case it is ideal to export them immediately (without  any  col‐
144       lector  system  restart).   In  this situation, the PMDA can inform all
145       running PMAPI clients that may have already explored the metric  names‐
146       pace (for example, using pmTraversePMNS(3)) of the change to the metric
147       namespace.
148
149       This is achieved using pmdaSetFlags(pmda, PMDA_EXT_NAMES_CHANGE)  which
150       will  result  in  the PMCD_NAMES_CHANGE state change notification being
151       sent to each PMAPI client on next fetch.  If the newly discovered  met‐
152       rics  have  label  metadata  associated, then the PMDA_EXT_LABEL_CHANGE
153       flag may also be set, which will result in the PMCD_LABEL_CHANGE  noti‐
154       fication being sent as well.
155
156       pmdaExtSetFlags  is  equivalent  to  pmdaSetFlags, and is provided as a
157       convenience interface in situations where the pmdaExt is  more  readily
158       available than the pmdaInterface structure.
159

COMMUNICATION ATTRIBUTES

161       Agents  that  make use of authentication or container attributes should
162       indicate this using the pmdaSetCommFlags interface.  This indicates the
163       need for these attributes to be communicated on the channel between the
164       PMDA and pmcd or local context client.  Valid flags  are  PMDA_FLAG_AU‐
165       THORIZE (for authentication related attributes) and PMDA_FLAG_CONTAINER
166       (for container name related attributes).
167

DIAGNOSTICS

169       pmdaInit will set dispatch->status to a value less than zero  if  there
170       is  an  error that would prevent the PMDA(3) from successfully running.
171       pmcd(1) will terminate the connection to the PMDA(3) if this occurs.
172
173       pmdaInit may issue any of these messages:
174
175       PMDA interface version interface not supported
176                      The interface version is not supported by pmdaInit.
177
178       Using pmdaFetch() but fetch call back not set
179                      The fetch callback, pmdaFetch(3), requires an additional
180                      callback to be provided using pmdaSetFetchCallBack(3).
181
182       Illegal instance domain inst for metric pmid
183                      The  instance  domain inst that was specified for metric
184                      pmid is not within the range of the instance domain  ta‐
185                      ble.
186
187       No help text path specified
188                      The  help  text  callback,  pmdaText(3), requires a help
189                      text file for the metrics to have been  opened,  however
190                      no path to the help text was specified as a command line
191                      option, or as an  argument  to  pmdaDSO(3)  or  pmdaDae‐
192                      mon(3).  This message is only a warning.
193
194       Direct mapping for metrics disabled @ num
195                      The  unit  numbers  of the metrics did not correspond to
196                      the index in the metric description table.   The  direct
197                      mapping  failed for metric number num in the metrics ta‐
198                      ble.  This is less efficient but is not  fatal  and  the
199                      message is only a warning.
200
201       Hashed mapping for metrics disabled @ num
202                      A  memory allocation failure occurred while building the
203                      hash table to index the metric description table.   This
204                      is  a  non-fatal  warning message - a fallback to linear
205                      searching will be automatically  performed  should  this
206                      situation arise.
207

CAVEAT

209       The  PMDA  must be using PMDA_INTERFACE_2 or later, as specified in the
210       call to pmdaDSO(3) or pmdaDaemon(3) to use pmdaInit.
211
212       The PMDA must use PMDA_INTERFACE_7 or later to issue state change noti‐
213       fications using pmdaSetFlags or pmdaExtSetFlags.
214

SEE ALSO

216       newhelp(1), pmcd(1), pmlogrewrite(1), PMAPI(3), PMDA(3), pmdaDaemon(3),
217       pmdaDSO(3), pmdaFetch(3), pmdaGetOpt(3),  pmdaText(3),  pmLookupDesc(3)
218       and pmTraversePMNS(3).
219
220
221
222Performance Co-Pilot                  PCP                          PMDAINIT(3)
Impressum