1PMDAINIT(3) Library Functions Manual PMDAINIT(3)
2
6 pmdaInit, pmdaRehash, pmdaSetFlags, pmdaSetCommFlags, pmdaExtSetFlags -
7 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);
16 void pmdaSetFlags(pmdaInterface *dispatch, int flags);
17 void pmdaSetCommFlags(pmdaInterface *dispatch, int flags);
18 void pmdaExtSetFlags(pmdaExt *pmda, int flags);
19 cc ... -lpcp_pmda -lpcp
21
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 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 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
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 static pmdaInstid _X[] = {
51 { 0, "X1" }, { 1, "X2" }
52 };
53 static pmdaInstid _Y[] = {
55 { 0, "Y1" }, { 1, "Y2" }
56 };
57 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 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 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 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 The final stage involves preparing the metric table lookup strategy.
93
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 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 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 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 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
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 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 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 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
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
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 pmdaInit may issue any of these messages:
174 PMDA interface version interface not supported
176 The interface version is not supported by pmdaInit.
177 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 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 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 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 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
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 The PMDA must use PMDA_INTERFACE_7 or later to issue state change noti‐
213 fications using pmdaSetFlags or pmdaExtSetFlags.
214
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).
219Performance Co-Pilot PCP PMDAINIT(3)