aboutsummaryrefslogtreecommitdiffstats
path: root/telemetry/vpp-collectd/common/plugin.h
blob: bbd69e00340be61be78e97b0a768e06556a86cfe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
/**
 * collectd - src/daemon/plugin.h
 * Copyright (C) 2005-2014  Florian octo Forster
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 * Authors:
 *   Florian octo Forster <octo at collectd.org>
 *   Sebastian Harl <sh at tokkee.org>
 **/

#ifndef PLUGIN_H
#define PLUGIN_H

#include "collectd.h"

#include "configfile.h"
#include "meta_data.h"
#include "utils_time.h"

#include <inttypes.h>
#include <pthread.h>

#define DS_TYPE_COUNTER 0
#define DS_TYPE_GAUGE 1
#define DS_TYPE_DERIVE 2
#define DS_TYPE_ABSOLUTE 3

#define DS_TYPE_TO_STRING(t)                                                   \
  (t == DS_TYPE_COUNTER)    ? "counter"                                        \
  : (t == DS_TYPE_GAUGE)    ? "gauge"                                          \
  : (t == DS_TYPE_DERIVE)   ? "derive"                                         \
  : (t == DS_TYPE_ABSOLUTE) ? "absolute"                                       \
                            : "unknown"

#ifndef LOG_ERR
#define LOG_ERR 3
#endif
#ifndef LOG_WARNING
#define LOG_WARNING 4
#endif
#ifndef LOG_NOTICE
#define LOG_NOTICE 5
#endif
#ifndef LOG_INFO
#define LOG_INFO 6
#endif
#ifndef LOG_DEBUG
#define LOG_DEBUG 7
#endif

#define NOTIF_MAX_MSG_LEN 256

#define NOTIF_FAILURE 1
#define NOTIF_WARNING 2
#define NOTIF_OKAY 4

#define plugin_interval (plugin_get_ctx().interval)

/*
 * Public data types
 */
struct identifier_s {
  char *host;
  char *plugin;
  char *plugin_instance;
  char *type;
  char *type_instance;
};
typedef struct identifier_s identifier_t;

typedef unsigned long long counter_t;
typedef double gauge_t;
typedef int64_t derive_t;
typedef uint64_t absolute_t;

union value_u {
  counter_t counter;
  gauge_t gauge;
  derive_t derive;
  absolute_t absolute;
};
typedef union value_u value_t;

struct value_list_s {
  value_t *values;
  size_t values_len;
  cdtime_t time;
  cdtime_t interval;
  char host[DATA_MAX_NAME_LEN];
  char plugin[DATA_MAX_NAME_LEN];
  char plugin_instance[DATA_MAX_NAME_LEN];
  char type[DATA_MAX_NAME_LEN];
  char type_instance[DATA_MAX_NAME_LEN];
  meta_data_t *meta;
};
typedef struct value_list_s value_list_t;

#define VALUE_LIST_INIT                                                        \
  { .values = NULL, .meta = NULL }

struct data_source_s {
  char name[DATA_MAX_NAME_LEN];
  int type;
  double min;
  double max;
};
typedef struct data_source_s data_source_t;

struct data_set_s {
  char type[DATA_MAX_NAME_LEN];
  size_t ds_num;
  data_source_t *ds;
};
typedef struct data_set_s data_set_t;

enum notification_meta_type_e {
  NM_TYPE_STRING,
  NM_TYPE_SIGNED_INT,
  NM_TYPE_UNSIGNED_INT,
  NM_TYPE_DOUBLE,
  NM_TYPE_BOOLEAN
};

typedef struct notification_meta_s {
  char name[DATA_MAX_NAME_LEN];
  enum notification_meta_type_e type;
  union {
    const char *nm_string;
    int64_t nm_signed_int;
    uint64_t nm_unsigned_int;
    double nm_double;
    bool nm_boolean;
  } nm_value;
  struct notification_meta_s *next;
} notification_meta_t;

typedef struct notification_s {
  int severity;
  cdtime_t time;
  char message[NOTIF_MAX_MSG_LEN];
  char host[DATA_MAX_NAME_LEN];
  char plugin[DATA_MAX_NAME_LEN];
  char plugin_instance[DATA_MAX_NAME_LEN];
  char type[DATA_MAX_NAME_LEN];
  char type_instance[DATA_MAX_NAME_LEN];
  notification_meta_t *meta;
} notification_t;

struct user_data_s {
  void *data;
  void (*free_func)(void *);
};
typedef struct user_data_s user_data_t;

enum cache_event_type_e { CE_VALUE_NEW, CE_VALUE_UPDATE, CE_VALUE_EXPIRED };

typedef struct cache_event_s {
  enum cache_event_type_e type;
  const value_list_t *value_list;
  const char *value_list_name;
  int ret;
} cache_event_t;

struct plugin_ctx_s {
  char *name;
  cdtime_t interval;
  cdtime_t flush_interval;
  cdtime_t flush_timeout;
};
typedef struct plugin_ctx_s plugin_ctx_t;

/*
 * Callback types
 */
typedef int (*plugin_init_cb)(void);
typedef int (*plugin_read_cb)(user_data_t *);
typedef int (*plugin_write_cb)(const data_set_t *, const value_list_t *,
                               user_data_t *);
typedef int (*plugin_flush_cb)(cdtime_t timeout, const char *identifier,
                               user_data_t *);
/* "missing" callback. Returns less than zero on failure, zero if other
 * callbacks should be called, greater than zero if no more callbacks should be
 * called. */
typedef int (*plugin_missing_cb)(const value_list_t *, user_data_t *);
/* "cache event" callback. CE_VALUE_NEW events are sent to all registered
 * callbacks. Callback should check if it interested in further CE_VALUE_UPDATE
 * and CE_VALUE_EXPIRED events for metric and set event->ret = 1 if so.
 */
typedef int (*plugin_cache_event_cb)(cache_event_t *, user_data_t *);
typedef void (*plugin_log_cb)(int severity, const char *message, user_data_t *);
typedef int (*plugin_shutdown_cb)(void);
typedef int (*plugin_notification_cb)(const notification_t *, user_data_t *);
/*
 * NAME
 *  plugin_set_dir
 *
 * DESCRIPTION
 *  Sets the current `plugindir'
 *
 * ARGUMENTS
 *  `dir'       Path to the plugin directory
 *
 * NOTES
 *  If `dir' is NULL the compiled in default `PLUGINDIR' is used.
 */
void plugin_set_dir(const char *dir);

/*
 * NAME
 *  plugin_load
 *
 * DESCRIPTION
 *  Searches the current `plugindir' (see `plugin_set_dir') for the plugin
 *  named $type and loads it. Afterwards the plugin's `module_register'
 *  function is called, which then calls `plugin_register' to register callback
 *  functions.
 *
 * ARGUMENTS
 *  `name'      Name of the plugin to load.
 *  `global'    Make this plugins symbols available for other shared libraries.
 *
 * RETURN VALUE
 *  Returns zero upon success, a value greater than zero if no plugin was found
 *  and a value below zero if an error occurs.
 *
 * NOTES
 *  Re-loading an already loaded module is detected and zero is returned in
 *  this case.
 */
int plugin_load(const char *name, bool global);
bool plugin_is_loaded(char const *name);

int plugin_init_all(void);
void plugin_read_all(void);
int plugin_read_all_once(void);
int plugin_shutdown_all(void);

/*
 * NAME
 *  plugin_write
 *
 * DESCRIPTION
 *  Calls the write function of the given plugin with the provided data set and
 *  value list. It differs from `plugin_dispatch_values' in that it does not
 *  update the cache, does not do threshold checking, call the chain subsystem
 *  and so on. It looks up the requested plugin and invokes the function, end
 *  of story.
 *
 * ARGUMENTS
 *  plugin     Name of the plugin. If NULL, the value is sent to all registered
 *             write functions.
 *  ds         Pointer to the data_set_t structure. If NULL, the data set is
 *             looked up according to the `type' member in the `vl' argument.
 *  vl         The actual value to be processed. Must not be NULL.
 *
 * RETURN VALUE
 *  Returns zero upon success or non-zero if an error occurred. If `plugin' is
 *  NULL and more than one plugin is called, an error is only returned if *all*
 *  plugins fail.
 *
 * NOTES
 *  This is the function used by the `write' built-in target. May be used by
 *  other target plugins.
 */
int plugin_write(const char *plugin, const data_set_t *ds,
                 const value_list_t *vl);

int plugin_flush(const char *plugin, cdtime_t timeout, const char *identifier);

/*
 * The `plugin_register_*' functions are used to make `config', `init',
 * `read', `write' and `shutdown' functions known to the plugin
 * infrastructure. Also, the data-formats are made public like this.
 */
int plugin_register_config(const char *name,
                           int (*callback)(const char *key, const char *val),
                           const char **keys, int keys_num);
int plugin_register_complex_config(const char *type,
                                   int (*callback)(oconfig_item_t *));
int plugin_register_init(const char *name, plugin_init_cb callback);
int plugin_register_read(const char *name, int (*callback)(void));
/* "user_data" will be freed automatically, unless
 * "plugin_register_complex_read" returns an error (non-zero). */
int plugin_register_complex_read(const char *group, const char *name,
                                 plugin_read_cb callback, cdtime_t interval,
                                 user_data_t const *user_data);
int plugin_register_write(const char *name, plugin_write_cb callback,
                          user_data_t const *user_data);
int plugin_register_flush(const char *name, plugin_flush_cb callback,
                          user_data_t const *user_data);
int plugin_register_missing(const char *name, plugin_missing_cb callback,
                            user_data_t const *user_data);
int plugin_register_cache_event(const char *name,
                                plugin_cache_event_cb callback,
                                user_data_t const *ud);
int plugin_register_shutdown(const char *name, plugin_shutdown_cb callback);
int plugin_register_data_set(const data_set_t *ds);
int plugin_register_log(const char *name, plugin_log_cb callback,
                        user_data_t const *user_data);
int plugin_register_notification(const char *name,
                                 plugin_notification_cb callback,
                                 user_data_t const *user_data);

int plugin_unregister_config(const char *name);
int plugin_unregister_complex_config(const char *name);
int plugin_unregister_init(const char *name);
int plugin_unregister_read(const char *name);
int plugin_unregister_read_group(const char *group);
int plugin_unregister_write(const char *name);
int plugin_unregister_flush(const char *name);
int plugin_unregister_missing(const char *name);
int plugin_unregister_cache_event(const char *name);
int plugin_unregister_shutdown(const char *name);
int plugin_unregister_data_set(const char *name);
int plugin_unregister_log(const char *name);
int plugin_unregister_notification(const char *name);

/*
 * NAME
 *  plugin_log_available_writers
 *
 * DESCRIPTION
 *  This function can be called to output a list of _all_ registered
 *  writers to the logfacility.
 *  Since some writers dynamically build their name it can be hard for
 *  the configuring person to know it. This function will fill this gap.
 */
void plugin_log_available_writers(void);

/*
 * NAME
 *  plugin_dispatch_values
 *
 * DESCRIPTION
 *  This function is called by reading processes with the values they've
 *  aquired. The function fetches the data-set definition (that has been
 *  registered using `plugin_register_data_set') and calls _all_ registered
 *  write-functions.
 *
 * ARGUMENTS
 *  `vl'        Value list of the values that have been read by a `read'
 *              function.
 */
int plugin_dispatch_values(value_list_t const *vl);

/*
 * NAME
 *  plugin_dispatch_multivalue
 *
 * SYNOPSIS
 *  plugin_dispatch_multivalue (vl, true, DS_TYPE_GAUGE,
 *                              "free", 42.0,
 *                              "used", 58.0,
 *                              NULL);
 *
 * DESCRIPTION
 *  Takes a list of type instances and values and dispatches that in a batch,
 *  making sure that all values have the same time stamp. If "store_percentage"
 *  is set to true, the "type" is set to "percent" and a percentage is
 *  calculated and dispatched, rather than the absolute values. Values that are
 *  NaN are dispatched as NaN and will not influence the total.
 *
 *  The variadic arguments is a list of type_instance / type pairs, that are
 *  interpreted as type "char const *" and type, encoded by their corresponding
 *  "store_type":
 *
 *     - "gauge_t"    when "DS_TYPE_GAUGE"
 *     - "absolute_t" when "DS_TYPE_ABSOLUTE"
 *     - "derive_t"   when "DS_TYPE_DERIVE"
 *     - "counter_t"  when "DS_TYPE_COUNTER"
 *
 *  The last argument must be
 *  a NULL pointer to signal end-of-list.
 *
 * RETURNS
 *  The number of values it failed to dispatch (zero on success).
 */
__attribute__((sentinel)) int plugin_dispatch_multivalue(value_list_t const *vl,
                                                         bool store_percentage,
                                                         int store_type, ...);

int plugin_dispatch_missing(const value_list_t *vl);
void plugin_dispatch_cache_event(enum cache_event_type_e event_type,
                                 unsigned long callbacks_mask, const char *name,
                                 const value_list_t *vl);

int plugin_dispatch_notification(const notification_t *notif);

void plugin_log(int level, const char *format, ...)
    __attribute__((format(printf, 2, 3)));

/* These functions return the parsed severity or less than zero on failure. */
int parse_log_severity(const char *severity);
int parse_notif_severity(const char *severity);

#define ERROR(...) plugin_log(LOG_ERR, __VA_ARGS__)
#define WARNING(...) plugin_log(LOG_WARNING, __VA_ARGS__)
#define NOTICE(...) plugin_log(LOG_NOTICE, __VA_ARGS__)
#define INFO(...) plugin_log(LOG_INFO, __VA_ARGS__)
#if COLLECT_DEBUG
#define DEBUG(...) plugin_log(LOG_DEBUG, __VA_ARGS__)
#else              /* COLLECT_DEBUG */
#define DEBUG(...) /* noop */
#endif             /* ! COLLECT_DEBUG */

/* This will log messages, prefixed by plugin name */
void daemon_log(int level, const char *format, ...)
    __attribute__((format(printf, 2, 3)));

#define P_ERROR(...) daemon_log(LOG_ERR, __VA_ARGS__)
#define P_WARNING(...) daemon_log(LOG_WARNING, __VA_ARGS__)
#define P_NOTICE(...) daemon_log(LOG_NOTICE, __VA_ARGS__)
#define P_INFO(...) daemon_log(LOG_INFO, __VA_ARGS__)

const data_set_t *plugin_get_ds(const char *name);

int plugin_notification_meta_add_string(notification_t *n, const char *name,
                                        const char *value);
int plugin_notification_meta_add_signed_int(notification_t *n, const char *name,
                                            int64_t value);
int plugin_notification_meta_add_unsigned_int(notification_t *n,
                                              const char *name, uint64_t value);
int plugin_notification_meta_add_double(notification_t *n, const char *name,
                                        double value);
int plugin_notification_meta_add_boolean(notification_t *n, const char *name,
                                         bool value);

int plugin_notification_meta_copy(notification_t *dst,
                                  const notification_t *src);

int plugin_notification_meta_free(notification_meta_t *n);

/*
 * Plugin context management.
 */

void plugin_init_ctx(void);

plugin_ctx_t plugin_get_ctx(void);
plugin_ctx_t plugin_set_ctx(plugin_ctx_t ctx);

/*
 * NAME
 *  plugin_get_interval
 *
 * DESCRIPTION
 *  This function returns the current value of the plugin's interval. The
 *  return value will be strictly greater than zero in all cases. If
 *  everything else fails, it will fall back to 10 seconds.
 */
cdtime_t plugin_get_interval(void);

/*
 * Context-aware thread management.
 */

int plugin_thread_create(pthread_t *thread, void *(*start_routine)(void *),
                         void *arg, char const *name);

/*
 * Plugins need to implement this
 */

void module_register(void);

#endif /* PLUGIN_H */