diff options
Diffstat (limited to 'telemetry/vpp-collectd/common')
| -rw-r--r-- | telemetry/vpp-collectd/common/README.md | 12 | ||||
| -rw-r--r-- | telemetry/vpp-collectd/common/common.h | 405 | ||||
| -rw-r--r-- | telemetry/vpp-collectd/common/meta_data.h | 71 | ||||
| -rw-r--r-- | telemetry/vpp-collectd/common/plugin.h | 485 |
4 files changed, 973 insertions, 0 deletions
diff --git a/telemetry/vpp-collectd/common/README.md b/telemetry/vpp-collectd/common/README.md new file mode 100644 index 000000000..e3b9c74f6 --- /dev/null +++ b/telemetry/vpp-collectd/common/README.md @@ -0,0 +1,12 @@ +# Headers for collectd plugins + +These headers are required for plugin development but are not shipped with the +`collectd` Ubuntu 20.04 package (as of May 2021): + +* [common.h](https://github.com/collectd/collectd/blob/main/src/utils/common/common.h) +* [plugin.h](https://github.com/collectd/collectd/blob/main/src/daemon/plugin.h) +* [meta_data.h](https://github.com/collectd/collectd/blob/main/src/utils/metadata/meta_data.h) + +Related issues: +* [GitHub](https://github.com/collectd/collectd/issues/3881) +* [Ubuntu](https://bugs.launchpad.net/ubuntu/+source/collectd/+bug/1929079) diff --git a/telemetry/vpp-collectd/common/common.h b/telemetry/vpp-collectd/common/common.h new file mode 100644 index 000000000..fce2d12bb --- /dev/null +++ b/telemetry/vpp-collectd/common/common.h @@ -0,0 +1,405 @@ +/** + * collectd - src/common.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> + * Niki W. Waibel <niki.waibel@gmx.net> + **/ + +#ifndef COMMON_H +#define COMMON_H + +#include "collectd.h" + +#include "plugin.h" + +#if HAVE_PWD_H +#include <pwd.h> +#endif + +#define sfree(ptr) \ + do { \ + free(ptr); \ + (ptr) = NULL; \ + } while (0) + +#define STATIC_ARRAY_SIZE(a) (sizeof(a) / sizeof(*(a))) + +#define IS_TRUE(s) \ + ((strcasecmp("true", (s)) == 0) || (strcasecmp("yes", (s)) == 0) || \ + (strcasecmp("on", (s)) == 0)) +#define IS_FALSE(s) \ + ((strcasecmp("false", (s)) == 0) || (strcasecmp("no", (s)) == 0) || \ + (strcasecmp("off", (s)) == 0)) + +struct rate_to_value_state_s { + value_t last_value; + cdtime_t last_time; + gauge_t residual; +}; +typedef struct rate_to_value_state_s rate_to_value_state_t; + +struct value_to_rate_state_s { + value_t last_value; + cdtime_t last_time; +}; +typedef struct value_to_rate_state_s value_to_rate_state_t; + +char *sstrncpy(char *dest, const char *src, size_t n); + +__attribute__((format(printf, 3, 4))) int ssnprintf(char *str, size_t size, + char const *format, ...); + +__attribute__((format(printf, 1, 2))) char *ssnprintf_alloc(char const *format, + ...); + +char *sstrdup(const char *s); +size_t sstrnlen(const char *s, size_t n); +char *sstrndup(const char *s, size_t n); +void *smalloc(size_t size); +char *sstrerror(int errnum, char *buf, size_t buflen); + +#ifndef ERRBUF_SIZE +#define ERRBUF_SIZE 256 +#endif + +#define STRERROR(e) sstrerror((e), (char[ERRBUF_SIZE]){0}, ERRBUF_SIZE) +#define STRERRNO STRERROR(errno) + +/* + * NAME + * sread + * + * DESCRIPTION + * Reads exactly `n' bytes or fails. Syntax and other behavior is analogous + * to `read(2)'. + * + * PARAMETERS + * `fd' File descriptor to write to. + * `buf' Buffer that is to be written. + * `count' Number of bytes in the buffer. + * + * RETURN VALUE + * Zero upon success or non-zero if an error occurred. `errno' is set in this + * case. + */ +int sread(int fd, void *buf, size_t count); + +/* + * NAME + * swrite + * + * DESCRIPTION + * Writes exactly `n' bytes or fails. Syntax and other behavior is analogous + * to `write(2)'. + * + * PARAMETERS + * `fd' File descriptor to write to. + * `buf' Buffer that is to be written. + * `count' Number of bytes in the buffer. + * + * RETURN VALUE + * Zero upon success or non-zero if an error occurred. `errno' is set in this + * case. + */ +int swrite(int fd, const void *buf, size_t count); + +/* + * NAME + * strsplit + * + * DESCRIPTION + * Splits a string into parts and stores pointers to the parts in `fields'. + * The characters split at are: " ", "\t", "\r", and "\n". + * + * PARAMETERS + * `string' String to split. This string will be modified. `fields' will + * contain pointers to parts of this string, so free'ing it + * will destroy `fields' as well. + * `fields' Array of strings where pointers to the parts will be stored. + * `size' Number of elements in the array. No more than `size' + * pointers will be stored in `fields'. + * + * RETURN VALUE + * Returns the number of parts stored in `fields'. + */ +int strsplit(char *string, char **fields, size_t size); + +/* + * NAME + * strjoin + * + * DESCRIPTION + * Joins together several parts of a string using `sep' as a separator. This + * is equivalent to the Perl built-in `join'. + * + * PARAMETERS + * `dst' Buffer where the result is stored. Can be NULL if you need to + * determine the required buffer size only. + * `dst_len' Length of the destination buffer. No more than this many + * bytes will be written to the memory pointed to by `dst', + * including the trailing null-byte. Must be zero if dst is + * NULL. + * `fields' Array of strings to be joined. + * `fields_num' Number of elements in the `fields' array. + * `sep' String to be inserted between any two elements of `fields'. + * This string is neither prepended nor appended to the result. + * Instead of passing "" (empty string) one can pass NULL. + * + * RETURN VALUE + * Returns the number of characters in the resulting string, excluding a + * tailing null byte. If this value is greater than or equal to "dst_len", the + * result in "dst" is truncated (but still null terminated). On error a + * negative value is returned. + */ +int strjoin(char *dst, size_t dst_len, char **fields, size_t fields_num, + const char *sep); + +/* + * NAME + * escape_slashes + * + * DESCRIPTION + * Removes slashes ("/") from "buffer". If buffer contains a single slash, + * the result will be "root". Leading slashes are removed. All other slashes + * are replaced with underscores ("_"). + * This function is used by plugin_dispatch_values() to escape all parts of + * the identifier. + * + * PARAMETERS + * `buffer' String to be escaped. + * `buffer_size' Size of the buffer. No more then this many bytes will be + * written to `buffer', including the trailing null-byte. + * + * RETURN VALUE + * Returns zero upon success and a value smaller than zero upon failure. + */ +int escape_slashes(char *buffer, size_t buffer_size); + +/** + * NAME + * escape_string + * + * DESCRIPTION + * escape_string quotes and escapes a string to be usable with collectd's + * plain text protocol. "simple" strings are left as they are, for example if + * buffer is 'simple' before the call, it will remain 'simple'. However, if + * buffer contains 'more "complex"' before the call, the returned buffer will + * contain '"more \"complex\""'. + * + * If the buffer is too small to contain the escaped string, the string will + * be truncated. However, leading and trailing double quotes, as well as an + * ending null byte are guaranteed. + * + * RETURN VALUE + * Returns zero on success, even if the string was truncated. Non-zero on + * failure. + */ +int escape_string(char *buffer, size_t buffer_size); + +/* + * NAME + * replace_special + * + * DESCRIPTION + * Replaces any special characters (anything that's not alpha-numeric or a + * dash) with an underscore. + * + * E.g. "foo$bar&" would become "foo_bar_". + * + * PARAMETERS + * `buffer' String to be handled. + * `buffer_size' Length of the string. The function returns after + * encountering a null-byte or reading this many bytes. + */ +void replace_special(char *buffer, size_t buffer_size); + +/* + * NAME + * strunescape + * + * DESCRIPTION + * Replaces any escaped characters in a string with the appropriate special + * characters. The following escaped characters are recognized: + * + * \t -> <tab> + * \n -> <newline> + * \r -> <carriage return> + * + * For all other escacped characters only the backslash will be removed. + * + * PARAMETERS + * `buf' String to be unescaped. + * `buf_len' Length of the string, including the terminating null-byte. + * + * RETURN VALUE + * Returns zero upon success, a value less than zero else. + */ +int strunescape(char *buf, size_t buf_len); + +/** + * Removed trailing newline characters (CR and LF) from buffer, which must be + * null terminated. Returns the length of the resulting string. + */ +__attribute__((nonnull(1))) size_t strstripnewline(char *buffer); + +/* + * NAME + * timeval_cmp + * + * DESCRIPTION + * Compare the two time values `tv0' and `tv1' and store the absolut value + * of the difference in the time value pointed to by `delta' if it does not + * equal NULL. + * + * RETURN VALUE + * Returns an integer less than, equal to, or greater than zero if `tv0' is + * less than, equal to, or greater than `tv1' respectively. + */ +int timeval_cmp(struct timeval tv0, struct timeval tv1, struct timeval *delta); + +/* make sure tv_usec stores less than a second */ +#define NORMALIZE_TIMEVAL(tv) \ + do { \ + (tv).tv_sec += (tv).tv_usec / 1000000; \ + (tv).tv_usec = (tv).tv_usec % 1000000; \ + } while (0) + +/* make sure tv_sec stores less than a second */ +#define NORMALIZE_TIMESPEC(tv) \ + do { \ + (tv).tv_sec += (tv).tv_nsec / 1000000000; \ + (tv).tv_nsec = (tv).tv_nsec % 1000000000; \ + } while (0) + +int check_create_dir(const char *file_orig); + +#ifdef HAVE_LIBKSTAT +#if HAVE_KSTAT_H +#include <kstat.h> +#endif +int get_kstat(kstat_t **ksp_ptr, char *module, int instance, char *name); +long long get_kstat_value(kstat_t *ksp, char *name); +#endif + +#ifndef HAVE_HTONLL +unsigned long long ntohll(unsigned long long n); +unsigned long long htonll(unsigned long long n); +#endif + +#if FP_LAYOUT_NEED_NOTHING +#define ntohd(d) (d) +#define htond(d) (d) +#elif FP_LAYOUT_NEED_ENDIANFLIP || FP_LAYOUT_NEED_INTSWAP +double ntohd(double d); +double htond(double d); +#else +#error \ + "Don't know how to convert between host and network representation of doubles." +#endif + +int format_name(char *ret, int ret_len, const char *hostname, + const char *plugin, const char *plugin_instance, + const char *type, const char *type_instance); +#define FORMAT_VL(ret, ret_len, vl) \ + format_name(ret, ret_len, (vl)->host, (vl)->plugin, (vl)->plugin_instance, \ + (vl)->type, (vl)->type_instance) +int format_values(char *ret, size_t ret_len, const data_set_t *ds, + const value_list_t *vl, bool store_rates); + +int parse_identifier(char *str, char **ret_host, char **ret_plugin, + char **ret_plugin_instance, char **ret_type, + char **ret_type_instance, char *default_host); +int parse_identifier_vl(const char *str, value_list_t *vl); +int parse_value(const char *value, value_t *ret_value, int ds_type); +int parse_values(char *buffer, value_list_t *vl, const data_set_t *ds); + +/* parse_value_file reads "path" and parses its content as an integer or + * floating point, depending on "ds_type". On success, the value is stored in + * "ret_value" and zero is returned. On failure, a non-zero value is returned. + */ +int parse_value_file(char const *path, value_t *ret_value, int ds_type); + +#if !HAVE_GETPWNAM_R +struct passwd; +int getpwnam_r(const char *name, struct passwd *pwbuf, char *buf, size_t buflen, + struct passwd **pwbufp); +#endif + +int notification_init(notification_t *n, int severity, const char *message, + const char *host, const char *plugin, + const char *plugin_instance, const char *type, + const char *type_instance); +#define NOTIFICATION_INIT_VL(n, vl) \ + notification_init(n, NOTIF_FAILURE, NULL, (vl)->host, (vl)->plugin, \ + (vl)->plugin_instance, (vl)->type, (vl)->type_instance) + +typedef int (*dirwalk_callback_f)(const char *dirname, const char *filename, + void *user_data); +int walk_directory(const char *dir, dirwalk_callback_f callback, + void *user_data, int hidden); +/* Returns the number of bytes read or negative on error. */ +ssize_t read_file_contents(char const *filename, void *buf, size_t bufsize); +/* Writes the contents of the file into the buffer with a trailing NUL. + * Returns the number of bytes written to the buffer or negative on error. */ +ssize_t read_text_file_contents(char const *filename, char *buf, + size_t bufsize); + +counter_t counter_diff(counter_t old_value, counter_t new_value); + +/* Convert a rate back to a value_t. When converting to a derive_t, counter_t + * or absolute_t, take fractional residuals into account. This is important + * when scaling counters, for example. + * Returns zero on success. Returns EAGAIN when called for the first time; in + * this case the value_t is invalid and the next call should succeed. Other + * return values indicate an error. */ +int rate_to_value(value_t *ret_value, gauge_t rate, + rate_to_value_state_t *state, int ds_type, cdtime_t t); + +int value_to_rate(gauge_t *ret_rate, value_t value, int ds_type, cdtime_t t, + value_to_rate_state_t *state); + +/* Converts a service name (a string) to a port number + * (in the range [1-65535]). Returns less than zero on error. */ +int service_name_to_port_number(const char *service_name); + +/* Sets various, non-default, socket options */ +void set_sock_opts(int sockfd); + +/** Parse a string to a derive_t value. Returns zero on success or non-zero on + * failure. If failure is returned, ret_value is not touched. */ +int strtoderive(const char *string, derive_t *ret_value); + +/** Parse a string to a gauge_t value. Returns zero on success or non-zero on + * failure. If failure is returned, ret_value is not touched. */ +int strtogauge(const char *string, gauge_t *ret_value); + +int strarray_add(char ***ret_array, size_t *ret_array_len, char const *str); +void strarray_free(char **array, size_t array_len); + +/** Check if the current process benefits from the capability passed in + * argument. Returns zero if it does, less than zero if it doesn't or on error. + * See capabilities(7) for the list of possible capabilities. + * */ +int check_capability(int arg); + +#endif /* COMMON_H */ diff --git a/telemetry/vpp-collectd/common/meta_data.h b/telemetry/vpp-collectd/common/meta_data.h new file mode 100644 index 000000000..203b14607 --- /dev/null +++ b/telemetry/vpp-collectd/common/meta_data.h @@ -0,0 +1,71 @@ +/** + * collectd - src/meta_data.h + * Copyright (C) 2008-2011 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> + **/ + +#ifndef META_DATA_H +#define META_DATA_H + +#include "collectd.h" + +/* + * Defines + */ +#define MD_TYPE_STRING 1 +#define MD_TYPE_SIGNED_INT 2 +#define MD_TYPE_UNSIGNED_INT 3 +#define MD_TYPE_DOUBLE 4 +#define MD_TYPE_BOOLEAN 5 + +struct meta_data_s; +typedef struct meta_data_s meta_data_t; + +meta_data_t *meta_data_create(void); +meta_data_t *meta_data_clone(meta_data_t *orig); +int meta_data_clone_merge(meta_data_t **dest, meta_data_t *orig); +void meta_data_destroy(meta_data_t *md); + +int meta_data_exists(meta_data_t *md, const char *key); +int meta_data_type(meta_data_t *md, const char *key); +int meta_data_toc(meta_data_t *md, char ***toc); +int meta_data_delete(meta_data_t *md, const char *key); + +int meta_data_add_string(meta_data_t *md, const char *key, const char *value); +int meta_data_add_signed_int(meta_data_t *md, const char *key, int64_t value); +int meta_data_add_unsigned_int(meta_data_t *md, const char *key, + uint64_t value); +int meta_data_add_double(meta_data_t *md, const char *key, double value); +int meta_data_add_boolean(meta_data_t *md, const char *key, bool value); + +int meta_data_get_string(meta_data_t *md, const char *key, char **value); +int meta_data_get_signed_int(meta_data_t *md, const char *key, int64_t *value); +int meta_data_get_unsigned_int(meta_data_t *md, const char *key, + uint64_t *value); +int meta_data_get_double(meta_data_t *md, const char *key, double *value); +int meta_data_get_boolean(meta_data_t *md, const char *key, bool *value); + +/* Returns the value as a string, regardless of the type. */ +int meta_data_as_string(meta_data_t *md, const char *key, char **value); + +#endif /* META_DATA_H */ diff --git a/telemetry/vpp-collectd/common/plugin.h b/telemetry/vpp-collectd/common/plugin.h new file mode 100644 index 000000000..0e75adc9b --- /dev/null +++ b/telemetry/vpp-collectd/common/plugin.h @@ -0,0 +1,485 @@ +/** + * 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 */ |