From: Florian Forster Date: Sat, 23 Feb 2008 16:30:34 +0000 (+0100) Subject: src/utils_logtail.h: Completed the documentation. X-Git-Tag: collectd-4.4.0~91^2~3 X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=8e2f27a795a6732a4bc72594b440159b1e7bab47;p=collectd.git src/utils_logtail.h: Completed the documentation. --- diff --git a/src/utils_logtail.c b/src/utils_logtail.c index 94fdb790..b0ca1ace 100644 --- a/src/utils_logtail.c +++ b/src/utils_logtail.c @@ -31,6 +31,15 @@ #include "utils_tail.h" #include "utils_logtail.h" +struct cu_logtail_simple_s +{ + 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]; +}; +typedef struct cu_logtail_simple_s cu_logtail_simple_t; + struct cu_logtail_match_s { cu_match_t *match; @@ -189,13 +198,17 @@ int logtail_add_match_simple (cu_logtail_t *obj, match_destroy (match); return (-1); } + memset (user_data, '\0', sizeof (cu_logtail_simple_t)); sstrncpy (user_data->plugin, plugin, sizeof (user_data->plugin)); - sstrncpy (user_data->plugin_instance, plugin_instance, - sizeof (user_data->plugin_instance)); + if (plugin_instance != NULL) + sstrncpy (user_data->plugin_instance, plugin_instance, + sizeof (user_data->plugin_instance)); + sstrncpy (user_data->type, type, sizeof (user_data->type)); - sstrncpy (user_data->type_instance, type_instance, - sizeof (user_data->type_instance)); + if (type_instance != NULL) + sstrncpy (user_data->type_instance, type_instance, + sizeof (user_data->type_instance)); status = logtail_add_match (obj, match, simple_submit_match, user_data, free); @@ -224,6 +237,9 @@ int logtail_read (cu_logtail_t *obj) { cu_logtail_match_t *lt_match = obj->matches + i; + if (lt_match->submit == NULL) + continue; + (*lt_match->submit) (lt_match->match, lt_match->user_data); } diff --git a/src/utils_logtail.h b/src/utils_logtail.h index 8b193408..c8f945e9 100644 --- a/src/utils_logtail.h +++ b/src/utils_logtail.h @@ -21,8 +21,11 @@ * Florian Forster * * Description: - * Encapsulates useful code to plugins which must parse a log file. - * + * `logtail' uses `utils_tail' and `utils_match' to tail a file and try to + * match it using several regular expressions. Matches are then passed to + * user-provided callback functions or default handlers. This should keep all + * of the parsing logic out of the actual plugin, which only operate with + * regular expressions. */ #include "utils_match.h" @@ -30,15 +33,6 @@ struct cu_logtail_s; typedef struct cu_logtail_s cu_logtail_t; -struct cu_logtail_simple_s -{ - 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]; -}; -typedef struct cu_logtail_simple_s cu_logtail_simple_t; - /* * NAME * logtail_create @@ -48,7 +42,6 @@ typedef struct cu_logtail_simple_s cu_logtail_simple_t; * * PARAMETERS * `filename' The name to read data from. - * `plugin' The plugin name to use when dispatching values. * * RETURN VALUE * Returns NULL upon failure, non-NULL otherwise. @@ -69,19 +62,20 @@ void logtail_destroy (cu_logtail_t *obj); /* * NAME - * logtail_add_match_simple + * logtail_add_match * * DESCRIPTION - * Adds a match, in form of a regular expression, to the `cu_logtail_t' - * object. The values matched by that regular expression are dispatched to - * the daemon using the supplied `type' and `type_instance' fields. - * - * PARAMETERS - * `obj' - * `type' - * `type_instance' - * `match_ds_type' - * `regex' + * Adds a match, in form of a `cu_match_t' object, to the object. + * After data has been read from the logfile (using utils_tail) the callback + * function `submit_match' is called with the match object and the user + * supplied data. + * Please note that his function is called regardless whether this match + * matched any lines recently or not. + * When `logtail_destroy' is called the `user_data' pointer is freed using + * the `free_user_data' callback - if it is not NULL. + * When using this interface the `logtail' module doesn't dispatch any values + * itself - all that has to happen in either the match-callbacks or the + * submit_match callback. * * RETURN VALUE * Zero upon success, non-zero otherwise. @@ -91,6 +85,22 @@ int logtail_add_match (cu_logtail_t *obj, cu_match_t *match, void *user_data, void (*free_user_data) (void *user_data)); +/* + * NAME + * logtail_add_match_simple + * + * DESCRIPTION + * A simplified version of `logtail_add_match'. The regular expressen `regex' + * must match a number, which is then dispatched according to `ds_type'. See + * the `match_create_simple' function in utils_match.h for a description how + * this flag effects calculation of a new value. + * The values gathered are dispatched by the logtail module in this case. The + * passed `plugin', `plugin_instance', `type', and `type_instance' are + * directly used when submitting these values. + * + * RETURN VALUE + * Zero upon success, non-zero otherwise. + */ int logtail_add_match_simple (cu_logtail_t *obj, const char *regex, int ds_type, const char *plugin, const char *plugin_instance, @@ -101,19 +111,12 @@ int logtail_add_match_simple (cu_logtail_t *obj, * logtail_read * * DESCRIPTION - * Looks for more data in the log file, sends each line - * through the given function, and submits the counters to - * collectd. - * - * PARAMETERS - * `instances' The handle used to identify the plugin. - * - * `func' The function used to parse each line from the log. - * - * `plugin' The name of the plugin. - * - * `names' An array of counter names in the same order as the - * counters themselves. + * This function should be called periodically by plugins. It reads new lines + * from the logfile using `utils_tail' and tries to match them using all + * added `utils_match' objects. + * After all lines have been read and processed, the submit_match callback is + * called or, in case of logtail_add_match_simple, the data is dispatched to + * the daemon directly. * * RETURN VALUE * Zero on success, nonzero on failure.