1 /*
2 * SysDB - src/include/core/plugin.h
3 * Copyright (C) 2012 Sebastian 'tokkee' Harl <sh@tokkee.org>
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
19 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
28 #ifndef SDB_CORE_PLUGIN_H
29 #define SDB_CORE_PLUGIN_H 1
31 #include "sysdb.h"
32 #include "core/object.h"
33 #include "core/store.h"
34 #include "core/time.h"
35 #include "core/timeseries.h"
37 #include "liboconfig/oconfig.h"
39 #include <stdarg.h>
40 #include <stdbool.h>
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
46 typedef struct {
47 sdb_time_t interval;
48 } sdb_plugin_ctx_t;
49 #define SDB_PLUGIN_CTX_INIT { 0 }
51 typedef struct {
52 char *plugin_name;
53 char *filename;
55 /* public attributes */
56 char *description;
57 char *copyright;
58 char *license;
60 int version;
61 int plugin_version;
62 } sdb_plugin_info_t;
63 #define SDB_PLUGIN_INFO_INIT { \
64 /* plugin_name */ NULL, /* filename */ NULL, /* desc */ NULL, \
65 /* copyright */ NULL, /* license */ NULL, \
66 /* version */ -1, /* plugin_version */ -1 }
68 /* this should be used in the header of a plugin to avoid
69 * missing prototype warnings/errors for the plugin init
70 * function */
71 #define SDB_PLUGIN_MAGIC \
72 int sdb_module_init(sdb_plugin_info_t *info)
74 typedef struct {
75 bool do_loop;
76 sdb_time_t default_interval;
77 } sdb_plugin_loop_t;
78 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
80 /*
81 * sdb_plugin_load:
82 * Load (any type of) plugin by loading the shared object file and calling the
83 * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the
84 * behavior of the plugin. If specified, the plugin will be looked up in
85 * 'basedir', else it defaults to the package libdir.
86 */
87 int
88 sdb_plugin_load(const char *basedir, const char *name,
89 const sdb_plugin_ctx_t *plugin_ctx);
91 /*
92 * sdb_plugin_set_info:
93 * Fill in the fields of the sdb_plugin_info_t object passed to the
94 * sdb_module_init function. This information is used to identify the plugin
95 * and also to provide additional information to the user.
96 */
97 enum {
98 SDB_PLUGIN_INFO_DESC, /* plugin description: string */
99 SDB_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */
100 SDB_PLUGIN_INFO_LICENSE, /* plugin license: string */
101 SDB_PLUGIN_INFO_VERSION, /* libsysdb version: integer */
102 SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
103 };
105 int
106 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
108 /*
109 * plugin callback functions:
110 * See the description of the respective register function for what arguments
111 * the callbacks expect.
112 *
113 * The specified name of callback functions is prepended with the plugin name
114 * before being registered with the core.
115 */
117 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
118 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
119 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
120 typedef char *(*sdb_plugin_cname_cb)(const char *name,
121 sdb_object_t *user_data);
122 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
123 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
124 sdb_object_t *user_data);
126 typedef sdb_timeseries_t *(*sdb_plugin_fetch_ts_cb)(const char *id,
127 sdb_timeseries_opts_t *opts, sdb_object_t *user_data);
129 /*
130 * sdb_plugin_register_config:
131 * Register a "config" function. This will be used to pass on the
132 * configuration for a plugin. The plugin has to make sure that the function
133 * can be called multiple times in order to process multiple <Plugin> blocks
134 * specified in the configuration file(s).
135 *
136 * Returns:
137 * - 0 on success
138 * - a negative value else
139 */
140 int
141 sdb_plugin_register_config(sdb_plugin_config_cb callback);
143 /*
144 * sdb_plugin_register_init:
145 * Register an "init" function. All "init" functions will be called after
146 * finishing the config parsing and before starting any other work. The
147 * functions will be called in the same order as they have been registered,
148 * that is, functions of different plugins will be called in the same order as
149 * the appropriate "Load" statements in the config file.
150 *
151 * If the "init" function returns a non-zero value, *all* callbacks of the
152 * plugin will be unloaded.
153 *
154 * Arguments:
155 * - user_data: If specified, this will be passed on to each call of the
156 * callback. The function will take ownership of the object, that is,
157 * increment the reference count by one. In case the caller does not longer
158 * use the object for other purposes, it should thus deref it.
159 *
160 * Returns:
161 * - 0 on success
162 * - a negative value else
163 */
164 int
165 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
166 sdb_object_t *user_data);
168 /*
169 * sdb_plugin_register_collector:
170 * Register a "collector" function. This is where a backend is doing its main
171 * work. This function will be called whenever an update of a backend has been
172 * requested (either by regular interval or by user request). The backend
173 * should then query the appropriate data-source and submit all values to the
174 * core.
175 *
176 * Arguments:
177 * - interval: Specifies the regular interval at which to update the backend.
178 * If this is NULL, global settings will be used.
179 * - user_data: If specified, this will be passed on to each call of the
180 * callback. The function will take ownership of the object, that is,
181 * increment the reference count by one. In case the caller does not longer
182 * use the object for other purposes, it should thus deref it.
183 *
184 * Returns:
185 * - 0 on success
186 * - a negative value else
187 */
188 int
189 sdb_plugin_register_collector(const char *name,
190 sdb_plugin_collector_cb callback,
191 const sdb_time_t *interval, sdb_object_t *user_data);
193 /*
194 * sdb_plugin_register_cname:
195 * Register a "cname" (canonicalize name) function. This type of function is
196 * called whenever a host is stored. It accepts the hostname and returns a
197 * canonicalized hostname which will then be used to actually store the host.
198 * If multiple such callbacks are registered, each one of them will be called
199 * in the order they have been registered, each one receiving the result of
200 * the previous callback. If the function returns NULL, the original hostname
201 * is not changed. Any other value has to be dynamically allocated. It will be
202 * freed later on by the core.
203 *
204 * Returns:
205 * - 0 on success
206 * - a negative value else
207 */
208 int
209 sdb_plugin_register_cname(const char *name, sdb_plugin_cname_cb callback,
210 sdb_object_t *user_data);
212 /*
213 * sdb_plugin_register_shutdown:
214 * Register a "shutdown" function to be called after stopping all update
215 * processes and before shutting down the daemon.
216 *
217 * Arguments:
218 * - user_data: If specified, this will be passed on to each call of the
219 * callback. The function will take ownership of the object, that is,
220 * increment the reference count by one. In case the caller does not longer
221 * use the object for other purposes, it should thus deref it.
222 */
223 int
224 sdb_plugin_register_shutdown(const char *name,
225 sdb_plugin_shutdown_cb callback,
226 sdb_object_t *user_data);
228 /*
229 * sdb_plugin_register_log:
230 * Register a "log" function to be called whenever logging is to be done.
231 *
232 * Arguments:
233 * - user_data: If specified, this will be passed on to each call of the
234 * callback. The function will take ownership of the object, that is,
235 * increment the reference count by one. In case the caller does not longer
236 * use the object for other purposes, it should thus deref it.
237 */
238 int
239 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
240 sdb_object_t *user_data);
242 /*
243 * sdb_plugin_register_ts_fetcher:
244 * Register a "time-series fetcher" function to be called whenever retrieving
245 * a time-series from a data-store. The callback will receive an identifier
246 * describing where to retrieve the data from (e.g. a filename or some kind of
247 * URL) and options which further describe the query.
248 *
249 * The name is used literally (without prepending the plugin name) to look up
250 * the appropriate fetcher callback.
251 *
252 * Arguments:
253 * - user_data: If specified, this will be passed on to each call of the
254 * callback. The function will take ownership of the object, that is,
255 * increment the reference count by one. In case the caller does not longer
256 * use the object for other purposes, it should thus deref it.
257 */
258 int
259 sdb_plugin_register_ts_fetcher(const char *name,
260 sdb_plugin_fetch_ts_cb callback, sdb_object_t *user_data);
262 /*
263 * sdb_plugin_register_writer:
264 * Register a "writer" implementation to be used when adding an object to the
265 * store. It is invalid to register an incomplete writer which does not
266 * implement all of the writer interface.
267 *
268 * Arguments:
269 * - user_data: If specified, this will be passed on to each call of the
270 * callback. The function will take ownership of the object, that is,
271 * increment the reference count by one. In case the caller does not longer
272 * use the object for other purposes, it should thus deref it.
273 */
274 int
275 sdb_plugin_register_writer(const char *name,
276 sdb_store_writer_t *writer, sdb_object_t *user_data);
278 /*
279 * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
280 * The plugin context defines a set of settings that are available whenever a
281 * plugin has been called. It may be used to pass around various information
282 * between the different component of the library without having each and
283 * every plugin care about it.
284 *
285 * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location
286 * pointed to by 'old'.
287 */
288 sdb_plugin_ctx_t
289 sdb_plugin_get_ctx(void);
290 int
291 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old);
293 /*
294 * sdb_plugin_current:
295 * Retrieve information about the plugin (if any) from which the current call
296 * into the core originated. The return value may not be modified.
297 *
298 * Returns:
299 * - information about the current plugin if we were called from some
300 * plugin's callback function
301 * - NULL else
302 */
303 const sdb_plugin_info_t *
304 sdb_plugin_current(void);
306 /*
307 * sdb_plugin_configure:
308 * Configure the plugin called 'name' using the config tree 'ci'. The plugin
309 * name is the same as the one used when loading the plugin.
310 *
311 * Returns:
312 * - 0 on success
313 * - a negative value else
314 */
315 int
316 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
318 /*
319 * sdb_plugin_reconfigure_init, sdb_plugin_reconfigure_finish:
320 * Reconfigure all plugins. This happens in multiple steps: first, call
321 * sdb_plugin_reconfigure_init to deconfigure all plugins by calling their
322 * config callbacks with a NULL config tree and unregistering all callbacks.
323 * Then, sdb_plugin_configure and other functions may be used to provide the
324 * new configuration or load new plugins. For all plugins which were already
325 * loaded before, sdb_module_init will be called with a NULL argument when
326 * reloading them.
327 * Finally, sdb_plugin_reconfigure_finish will clean up leftover pieces, like
328 * unloading plugins which are no longer in use.
329 *
330 * Returns:
331 * - 0 on success
332 * - a negative value else
333 */
334 int
335 sdb_plugin_reconfigure_init(void);
336 int
337 sdb_plugin_reconfigure_finish(void);
339 /*
340 * sdb_plugin_init_all:
341 * Initialize all plugins using their registered "init" function.
342 *
343 * Returns:
344 * The number of failed initializations.
345 */
346 int
347 sdb_plugin_init_all(void);
349 /*
350 * sdb_plugin_shutdown_all:
351 * Shutdown all plugins using their registered "shutdown" function.
352 *
353 * Returns:
354 * The number of failed shutdowns.
355 */
356 int
357 sdb_plugin_shutdown_all(void);
359 /*
360 * sdb_plugin_collector_loop:
361 * Loop until loop->do_loop is false, calling the next collector function on
362 * each iteration and once its next update interval is passed.
363 *
364 * Returns:
365 * - 0 on success
366 * - a negative value else
367 */
368 int
369 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
371 /*
372 * sdb_plugin_cname:
373 * Returns the canonicalized hostname. The given hostname argument has to
374 * point to dynamically allocated memory and might be freed by the function.
375 * The return value will also be dynamically allocated (but it might be
376 * unchanged) and has to be freed by the caller.
377 */
378 char *
379 sdb_plugin_cname(char *hostname);
381 /*
382 * sdb_plugin_log:
383 * Log the specified message using all registered log callbacks. The message
384 * will be logged with the specified priority.
385 */
386 int
387 sdb_plugin_log(int prio, const char *msg);
389 /*
390 * sdb_plugin_logf:
391 * Log a formatted message. See sdb_plugin_log for more information.
392 */
393 int
394 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap)
395 __attribute__((format(printf, 2, 0)));
396 int
397 sdb_plugin_logf(int prio, const char *fmt, ...)
398 __attribute__((format(printf, 2, 3)));
400 /*
401 * sdb_plugin_fetch_timeseries:
402 * Fetch the time-series identified by 'id' from a backend data-store of the
403 * specified 'type'. The type has to match an existing time-series fetcher
404 * callback's name. The identifier is passed through to the callback which
405 * then needs to make sense of it. The time-series option specify which data
406 * to fetch.
407 *
408 * Returns:
409 * - a time-series on success
410 * - NULL else
411 */
412 sdb_timeseries_t *
413 sdb_plugin_fetch_timeseries(const char *type, const char *id,
414 sdb_timeseries_opts_t *opts);
416 /*
417 * sdb_plugin_store_host, sdb_plugin_store_service, sdb_plugin_store_metric,
418 * sdb_plugin_store_attribute, sdb_plugin_store_service_attribute,
419 * sdb_plugin_store_metric_attribute:
420 * Store an object in the database by sending it to all registered store
421 * writer plugins.
422 *
423 * Returns:
424 * - 0 on success
425 * - a negative value else
426 */
427 int
428 sdb_plugin_store_host(const char *name, sdb_time_t last_update);
429 int
430 sdb_plugin_store_service(const char *hostname, const char *name,
431 sdb_time_t last_update);
432 int
433 sdb_plugin_store_metric(const char *hostname, const char *name,
434 sdb_metric_store_t *store, sdb_time_t last_update);
435 int
436 sdb_plugin_store_attribute(const char *hostname, const char *key,
437 const sdb_data_t *value, sdb_time_t last_update);
438 int
439 sdb_plugin_store_service_attribute(const char *hostname, const char *service,
440 const char *key, const sdb_data_t *value, sdb_time_t last_update);
441 int
442 sdb_plugin_store_metric_attribute(const char *hostname, const char *metric,
443 const char *key, const sdb_data_t *value, sdb_time_t last_update);
445 #ifdef __cplusplus
446 } /* extern "C" */
447 #endif
449 #endif /* ! SDB_CORE_PLUGIN_H */
451 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */