1 /*
2 * collectd - src/utils_tail_match.h
3 * Copyright (C) 2007-2008 C-Ware, Inc.
4 * Copyright (C) 2008 Florian Forster
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; only version 2 of the License is applicable.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18 *
19 * Authors:
20 * Luke Heberling <lukeh at c-ware.com>
21 * Florian Forster <octo at verplant.org>
22 *
23 * Description:
24 * `tail_match' uses `utils_tail' and `utils_match' to tail a file and try to
25 * match it using several regular expressions. Matches are then passed to
26 * user-provided callback functions or default handlers. This should keep all
27 * of the parsing logic out of the actual plugin, which only operate with
28 * regular expressions.
29 */
31 #include "utils_match.h"
33 struct cu_tail_match_s;
34 typedef struct cu_tail_match_s cu_tail_match_t;
36 /*
37 * NAME
38 * tail_match_create
39 *
40 * DESCRIPTION
41 * Allocates, initializes and returns a new `cu_tail_match_t' object.
42 *
43 * PARAMETERS
44 * `filename' The name to read data from.
45 *
46 * RETURN VALUE
47 * Returns NULL upon failure, non-NULL otherwise.
48 */
49 cu_tail_match_t *tail_match_create (const char *filename);
51 /*
52 * NAME
53 * tail_match_destroy
54 *
55 * DESCRIPTION
56 * Releases resources used by the `cu_tail_match_t' object.
57 *
58 * PARAMETERS
59 * The object to destroy.
60 */
61 void tail_match_destroy (cu_tail_match_t *obj);
63 /*
64 * NAME
65 * tail_match_add_match
66 *
67 * DESCRIPTION
68 * Adds a match, in form of a `cu_match_t' object, to the object.
69 * After data has been read from the logfile (using utils_tail) the callback
70 * function `submit_match' is called with the match object and the user
71 * supplied data.
72 * Please note that his function is called regardless whether this match
73 * matched any lines recently or not.
74 * When `tail_match_destroy' is called the `user_data' pointer is freed using
75 * the `free_user_data' callback - if it is not NULL.
76 * When using this interface the `tail_match' module doesn't dispatch any values
77 * itself - all that has to happen in either the match-callbacks or the
78 * submit_match callback.
79 *
80 * RETURN VALUE
81 * Zero upon success, non-zero otherwise.
82 */
83 int tail_match_add_match (cu_tail_match_t *obj, cu_match_t *match,
84 int (*submit_match) (cu_match_t *match, void *user_data),
85 void *user_data,
86 void (*free_user_data) (void *user_data));
88 /*
89 * NAME
90 * tail_match_add_match_simple
91 *
92 * DESCRIPTION
93 * A simplified version of `tail_match_add_match'. The regular expressen `regex'
94 * must match a number, which is then dispatched according to `ds_type'. See
95 * the `match_create_simple' function in utils_match.h for a description how
96 * this flag effects calculation of a new value.
97 * The values gathered are dispatched by the tail_match module in this case. The
98 * passed `plugin', `plugin_instance', `type', and `type_instance' are
99 * directly used when submitting these values.
100 *
101 * RETURN VALUE
102 * Zero upon success, non-zero otherwise.
103 */
104 int tail_match_add_match_simple (cu_tail_match_t *obj,
105 const char *regex, int ds_type,
106 const char *plugin, const char *plugin_instance,
107 const char *type, const char *type_instance);
109 /*
110 * NAME
111 * tail_match_read
112 *
113 * DESCRIPTION
114 * This function should be called periodically by plugins. It reads new lines
115 * from the logfile using `utils_tail' and tries to match them using all
116 * added `utils_match' objects.
117 * After all lines have been read and processed, the submit_match callback is
118 * called or, in case of tail_match_add_match_simple, the data is dispatched to
119 * the daemon directly.
120 *
121 * RETURN VALUE
122 * Zero on success, nonzero on failure.
123 */
124 int tail_match_read (cu_tail_match_t *obj);
126 /* vim: set sw=2 sts=2 ts=8 : */