1PMDAINIT(3) Library Functions Manual PMDAINIT(3)
2
6 pmdaInit, pmdaRehash, pmdaSetData, pmdaExtGetData, pmdaExtSetData, pm‐
7 daSetFlags, pmdaSetCommFlags, pmdaExtSetFlags - initialize a PMDA
8
10 #include <pcp/pmapi.h>
11 #include <pcp/pmda.h>
12 void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms, int nindoms,
14 pmdaMetric *metrics, int nmetrics);
15 void pmdaRehash(pmdaExt *pmda, pmdaMetric *metrics, int nmetrics);
17 void pmdaSetFlags(pmdaInterface *dispatch, int flags);
19 void pmdaSetCommFlags(pmdaInterface *dispatch, int flags);
20 void pmdaExtSetFlags(pmdaExt *pmda, int flags);
21 void pmdaSetData(pmdaInterface *dispatch, void *data);
23 void pmdaExtSetData(pmdaExt *pmda, void *data);
24 void *pmdaExtGetData(pmdaExt *pmda);
25 cc ... -lpcp_pmda -lpcp
27
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 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 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
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 static pmdaInstid _X[] = {
57 { 0, "X1" }, { 1, "X2" }
58 };
59 static pmdaInstid _Y[] = {
61 { 0, "Y1" }, { 1, "Y2" }
62 };
63 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 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 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 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 The final stage involves preparing the metric table lookup strategy.
99
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 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 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 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 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
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 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 name‐
152 space (for example, using pmTraversePMNS(3)) of the change to the met‐
153 ric namespace.
154 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 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
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
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
183 The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the
184 call to pmdaDSO(3) or pmdaDaemon(3) to use pmdaInit.
185 The PMDA must use PMDA_INTERFACE_7 or later to issue state change noti‐
187 fications using pmdaSetFlags or pmdaExtSetFlags.
188
190 pmdaInit will set dispatch->status to a value less than zero if there
191 is an error that would prevent the PMDA(3) from successfully running.
192 pmcd(1) will terminate the connection to the PMDA(3) if this occurs.
193 pmdaInit may issue any of these messages:
195 PMDA interface version interface not supported
197 The interface version is not supported by pmdaInit.
198 Using pmdaFetch() but fetch call back not set
200 The fetch callback, pmdaFetch(3), requires an additional
201 callback to be provided using pmdaSetFetchCallBack(3).
202 Illegal instance domain inst for metric pmid
204 The instance domain inst that was specified for metric
205 pmid is not within the range of the instance domain ta‐
206 ble.
207 No help text path specified
209 The help text callback, pmdaText(3), requires a help
210 text file for the metrics to have been opened, however
211 no path to the help text was specified as a command line
212 option, or as an argument to pmdaDSO(3) or pmdaDae‐
213 mon(3). This message is only a warning.
214 Direct mapping for metrics disabled @ num
216 The unit numbers of the metrics did not correspond to
217 the index in the metric description table. The direct
218 mapping failed for metric number num in the metrics ta‐
219 ble. This is less efficient but is not fatal and the
220 message is only a warning.
221 Hashed mapping for metrics disabled @ num
223 A memory allocation failure occurred while building the
224 hash table to index the metric description table. This
225 is a non-fatal warning message - a fallback to linear
226 searching will be automatically performed should this
227 situation arise.
228
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).
233Performance Co-Pilot PCP PMDAINIT(3)