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

NAME

6       pmdaInit,   pmdaRehash,  pmdaSetData,  pmdaExtGetData,  pmdaExtSetData,
7       pmdaSetFlags, pmdaSetCommFlags, pmdaExtSetFlags - 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
16       void pmdaRehash(pmdaExt *pmda, pmdaMetric *metrics, int nmetrics);
17
18       void pmdaSetFlags(pmdaInterface *dispatch, int flags);
19       void pmdaSetCommFlags(pmdaInterface *dispatch, int flags);
20       void pmdaExtSetFlags(pmdaExt *pmda, int flags);
21
22       void pmdaSetData(pmdaInterface *dispatch, void *data);
23       void pmdaExtSetData(pmdaExt *pmda, void *data);
24       void *pmdaExtGetData(pmdaExt *pmda);
25
26       cc ... -lpcp_pmda -lpcp
27

DESCRIPTION

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

EXAMPLE

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

METRIC LOOKUP

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

METRIC CHANGES

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

COMMUNICATION ATTRIBUTES

167       Agents  that  make use of authentication or container attributes should
168       indicate this using the pmdaSetCommFlags interface.  This indicates the
169       need for these attributes to be communicated on the channel between the
170       PMDA and pmcd or local context client.  Valid flags  are  PMDA_FLAG_AU‐
171       THORIZE (for authentication related attributes) and PMDA_FLAG_CONTAINER
172       (for container name related attributes).
173

PRIVATE DATA

175       A facility for associating private PMDA data with the pmdaExt structure
176       is  available.  This allows a PMDA to associate an arbitrary (and typi‐
177       cally not global) pointer with the pmdaExt such that it  can  be  later
178       obtained during callbacks.  The interfaces for setting this pointer are
179       pmdaSetData and pmdaExtSetData, and pmdaExtGetData for subsequently re‐
180       trieving it.
181

DIAGNOSTICS

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

CAVEAT

223       The PMDA must be using PMDA_INTERFACE_2 or later, as specified  in  the
224       call to pmdaDSO(3) or pmdaDaemon(3) to use pmdaInit.
225
226       The PMDA must use PMDA_INTERFACE_7 or later to issue state change noti‐
227       fications using pmdaSetFlags or pmdaExtSetFlags.
228

SEE ALSO

230       newhelp(1), pmcd(1), pmlogrewrite(1), PMAPI(3), PMDA(3), pmdaDaemon(3),
231       pmdaDSO(3),  pmdaFetch(3),  pmdaGetOpt(3), pmdaText(3), pmLookupDesc(3)
232       and pmTraversePMNS(3).
233
234
235
236Performance Co-Pilot                  PCP                          PMDAINIT(3)
Impressum