MySQL  8.0.21
Source Code Documentation
log_builtins_filter.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
2 
3  This program is free software; you can redistribute it and/or modify
4  it under the terms of the GNU General Public License, version 2.0,
5  as published by the Free Software Foundation.
6 
7  This program is also distributed with certain software (including
8  but not limited to OpenSSL) that is licensed under separate terms,
9  as designated in a particular file or component or in included license
10  documentation. The authors of MySQL hereby grant you an additional
11  permission to link the program and your derivative works with the
12  separately licensed software that they have included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef LOG_BUILTINS_FILTER_H
24 #define LOG_BUILTINS_FILTER_H
25 
30 
31 #include "rwlock_scoped_lock.h"
32 
33 /*
34  services: log item filters
35 */
36 
37 typedef enum enum_log_filter_verb {
38  LOG_FILTER_UNDEF = 0, /**< not set */
39  LOG_FILTER_DROP = 1, /**< drop this log event */
40  LOG_FILTER_THROTTLE = 2, /**< rate-limit this line class */
41  LOG_FILTER_ITEM_SET = 3, /**< add field */
42  LOG_FILTER_ITEM_DEL = 4, /**< remove field */
43  LOG_FILTER_RETURN = 8, /**< stop filtering, run (next filter or) sinks */
44 
45  LOG_FILTER_CHAIN_AND = 4096, /**< no verb yet, part of a condition chain */
46  LOG_FILTER_CHAIN_OR = 4097 /**< no verb yet, part of a condition chain */
48 
49 typedef enum enum_log_filter_cond {
50  LOG_FILTER_COND_NONE = 0, /**< not set / unconditional */
51  LOG_FILTER_COND_EQ = 1, /**< equal */
52  LOG_FILTER_COND_NE = 2, /**< not equal */
53  LOG_FILTER_COND_LT = 3, /**< less than */
54  LOG_FILTER_COND_LE = 4, /**< less or equal */
55  LOG_FILTER_COND_GE = 5, /**< greater or equal */
56  LOG_FILTER_COND_GT = 6, /**< greater than */
57  LOG_FILTER_COND_PRESENT = 7, /**< field present */
58  LOG_FILTER_COND_ABSENT = 8, /**< field absent */
60 
61 /**
62  Note that if our condition requires absence of the key, and the
63  key does not exist, that constitutes success!
64 */
65 typedef enum enum_log_filter_match {
66  /** success */
68  /** failure */
70  /** don't know yet */
72  /** invalid value */
74  /** either both or neither operands must be strings */
76  /** comparator does not exist for this type (yet) */
79 
80 typedef enum enum_log_filter_apply {
81  /** all's well that applies well */
83  /** invalid argument, e.g. "keep -3 characters of this string" */
85  /** log line does not accept further items */
87  /** variant of malloc() failed */
89  /** action/verb not known/implement by this filter */
91  /** had a match for the condition/comparator, but not for the action/verb */
94 
95 typedef enum enum_log_filter_flags {
96  /** normal state */
98  /** used to identify rules that don't come from the rule engine, but were
99  injected by the server for emulation of legacy log_error_verbosity etc. */
101  /** rule temporarily disabled */
104 
105 typedef struct _log_filter_tag {
106  const char *filter_name; /**< name of the service that created this rule */
107  void *filter_data; /**< for ad lib use by said service. instance etc. */
109 
110 typedef struct _log_filter_rule {
111  ulong id; /**< index may change; this will not */
112  ulong jump; /**< default: 0.
113  action of an IF/ELSEIF/ELSE branch:
114  points behind last branch of this
115  IF-construct (we successfully matched
116  a condition, and executed its statement,
117  so leave this IF-construct as nothing
118  else will apply).
119  condition of an IF/ELSEIF:
120  points to next ELSEIF/ELSE, so we can
121  jump there if the condition fails.
122  */
123  log_item match; /**< compare to this item type/class/key/value etc */
124  log_filter_cond cond; /**< how to compare: < > == regex etc */
125  log_filter_verb verb; /**< what to do: drop, upvote, etc */
126  log_item aux; /**< aux: item to add/prio to set/throttle rate */
127 
128  // private state keeping
129 
130  /** for rate-limiting: at what time will current window end? */
132  /** for rate-limiting: window-size (in seconds) */
134  /** how many lines in this window matched? (both suppressed and not) */
136 
137  /** log_filter_flags (fix storage size) */
138  ulong flags;
139 
140  /** how often did this rule match? */
141  volatile int32 match_count;
142 
143  /** lock an individual rule (to update state keeping) */
146 
147 #define LOG_FILTER_RULE_MAX 512
148 
149 typedef struct _log_filter_ruleset {
150  /** creator of this rule */
152 
153  /** number of rules currently in ruleset */
155  /** maximum number of rules in this ruleset */
157  /** rules in this ruleset */
159  /**
160  lock for whole ruleset.
161 
162  - get a read lock to apply filter rules to event
163  - if a rule changes rule-internal state, like the occurrence count
164  for throttle, it must upgrade to write lock
165  => technically, internal state could use a per-rule lock,
166  but let's keep things simple for now
167  - changing the filter ruleset obviously also needs a write lock
168  */
171 
173  LOG_BUILTINS_LOCK_NONE = 0, /**< undefined */
174  LOG_BUILTINS_LOCK_SHARED = 1, /**< read-only lock */
175  LOG_BUILTINS_LOCK_EXCLUSIVE = 2 /**< read-write lock */
177 
178 BEGIN_SERVICE_DEFINITION(log_builtins_filter)
179 // run built-in filter, get/set its configuration
180 
181 /**
182  Create a new set of filter rules.
183 
184  @param tag tag for this ruleset
185  @param count number of rules to allocate
186 
187  @retval a pointer to a ruleset structure, or nullptr on failure
188 */
189 DECLARE_METHOD(log_filter_ruleset *, filter_ruleset_new,
190  (log_filter_tag * tag, size_t count));
191 
192 /**
193  Lock and get the filter rules.
194 
195  @param ruleset a ruleset (usually allocated with filter_ruleset_new())
196  @param locktype LOG_BUILTINS_LOCK_SHARED lock for reading
197  LOG_BUILTINS_LOCK_EXCLUSIVE lock for writing
198 
199  @retval 0 lock acquired
200  @retval !0 failed to acquire lock
201 */
202 DECLARE_METHOD(int, filter_ruleset_lock,
203  (log_filter_ruleset * ruleset,
205 
206 /**
207  Release lock on filter rules.
208 
209  @param ruleset a ruleset (usually allocated with filter_ruleset_new())
210 */
211 DECLARE_METHOD(void, filter_ruleset_unlock, (log_filter_ruleset * ruleset));
212 
213 /**
214  Drop an entire filter rule-set. Must hold lock.
215 
216  @param ruleset a ruleset * (usually allocated with filter_ruleset_new())
217 */
218 DECLARE_METHOD(void, filter_ruleset_drop, (log_filter_ruleset * ruleset));
219 
220 /**
221  Free an entire filter rule-set. Must hold lock. Lock will be destroyed.
222 
223  @param ruleset a ruleset * (usually allocated with filter_ruleset_new())
224  the pointer pointed to will be a nullptr on return.
225 */
226 DECLARE_METHOD(void, filter_ruleset_free, (log_filter_ruleset * *ruleset));
227 
228 /**
229  Move rules from one ruleset to another. Origin will be empty afterwards.
230 
231  @param from source ruleset
232  @param to destination ruleset
233 */
234 DECLARE_METHOD(int, filter_ruleset_move,
236 
237 /**
238  Initialize a new rule.
239  This clears the first unused rule. It does not update the rules
240  count; this is for the caller to do if it succeeds in setting up
241  the rule to its satisfaction. If the caller fails, it should
242  log_builtins_filter_rule_free() the incomplete rule.
243 
244  @param ruleset a ruleset (usually allocated with filter_ruleset_new())
245 
246  @return nullptr: could not initialize rule. Do not call rule_free.
247  !nullptr: the address of the rule. fill in. on success,
248  caller must increase rule count. on failure,
249  it must call rule_free.
250 */
251 DECLARE_METHOD(void *, filter_rule_init, (log_filter_ruleset * ruleset));
252 
253 /**
254  Apply all matching rules from a filter rule set to a given log line.
255 
256  @param ll the current log line
257 
258  @retval int number of matched rules
259 */
260 DECLARE_METHOD(int, filter_run, (log_filter_ruleset * ruleset, log_line *ll));
261 
262 END_SERVICE_DEFINITION(log_builtins_filter)
263 
264 /**
265  Temporary primitives for logging services.
266 */
267 BEGIN_SERVICE_DEFINITION(log_builtins_filter_debug)
268 DECLARE_METHOD(log_filter_ruleset *, filter_debug_ruleset_get, (void));
269 END_SERVICE_DEFINITION(log_builtins_filter_debug)
270 
271 #endif
undefined
Definition: log_builtins_filter.h:173
unsigned long long int ulonglong
Definition: my_inttypes.h:55
read-only lock
Definition: log_builtins_filter.h:174
rule temporarily disabled
Definition: log_builtins_filter.h:102
read-write lock
Definition: log_builtins_filter.h:175
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:45
const char * filter_name
name of the service that created this rule
Definition: log_builtins_filter.h:106
Specifies macros to define Components.
ssize_t count
Definition: memcached.c:386
less or equal
Definition: log_builtins_filter.h:54
had a match for the condition/comparator, but not for the action/verb
Definition: log_builtins_filter.h:92
either both or neither operands must be strings
Definition: log_builtins_filter.h:75
ulong id
index may change; this will not
Definition: log_builtins_filter.h:111
field absent
Definition: log_builtins_filter.h:58
#define LOG_FILTER_RULE_MAX
Definition: log_builtins_filter.h:147
enum_log_filter_cond
Definition: log_builtins_filter.h:49
add field
Definition: log_builtins_filter.h:41
ulong jump
default: 0.
Definition: log_builtins_filter.h:112
enum_log_filter_match
Note that if our condition requires absence of the key, and the key does not exist, that constitutes success!
Definition: log_builtins_filter.h:65
invalid argument, e.g.
Definition: log_builtins_filter.h:84
enum_log_filter_verb
Definition: log_builtins_filter.h:37
less than
Definition: log_builtins_filter.h:53
struct _log_filter_ruleset log_filter_ruleset
enum enum_log_filter_apply log_filter_apply
ulonglong throttle_window_end
for rate-limiting: at what time will current window end?
Definition: log_builtins_filter.h:131
log_line ("log event")
Definition: log_builtins_imp.h:126
equal
Definition: log_builtins_filter.h:51
enum enum_log_filter_flags log_filter_flags
Definition: log_builtins_filter.h:149
ulong flags
log_filter_flags (fix storage size)
Definition: log_builtins_filter.h:138
not set / unconditional
Definition: log_builtins_filter.h:50
log_item match
compare to this item type/class/key/value etc
Definition: log_builtins_filter.h:123
#define DECLARE_METHOD(retval, name, args)
log_filter_cond cond
how to compare: < > == regex etc
Definition: log_builtins_filter.h:124
mysql_rwlock_t rule_lock
lock an individual rule (to update state keeping)
Definition: log_builtins_filter.h:144
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:46
variant of malloc() failed
Definition: log_builtins_filter.h:88
log_filter_verb verb
what to do: drop, upvote, etc
Definition: log_builtins_filter.h:125
log line does not accept further items
Definition: log_builtins_filter.h:86
greater than
Definition: log_builtins_filter.h:56
stop filtering, run (next filter or) sinks
Definition: log_builtins_filter.h:43
volatile int32 match_count
how often did this rule match?
Definition: log_builtins_filter.h:141
remove field
Definition: log_builtins_filter.h:42
enum enum_log_builtins_lock log_builtins_filter_lock
ulong throttle_matches
how many lines in this window matched? (both suppressed and not)
Definition: log_builtins_filter.h:135
log_item aux
aux: item to add/prio to set/throttle rate
Definition: log_builtins_filter.h:126
struct _log_filter_tag log_filter_tag
log_filter_tag * tag
creator of this rule
Definition: log_builtins_filter.h:151
uint32_t uint32
Definition: my_inttypes.h:66
not equal
Definition: log_builtins_filter.h:52
enum enum_log_filter_cond log_filter_cond
enum_log_filter_flags
Definition: log_builtins_filter.h:95
all&#39;s well that applies well
Definition: log_builtins_filter.h:82
uint32 count
number of rules currently in ruleset
Definition: log_builtins_filter.h:154
#define END_SERVICE_DEFINITION(name)
success
Definition: log_builtins_filter.h:67
normal state
Definition: log_builtins_filter.h:97
rate-limit this line class
Definition: log_builtins_filter.h:40
not set
Definition: log_builtins_filter.h:38
greater or equal
Definition: log_builtins_filter.h:55
An instrumented rwlock structure.
Definition: mysql_rwlock_bits.h:50
field present
Definition: log_builtins_filter.h:57
mysql_rwlock_t ruleset_lock
lock for whole ruleset.
Definition: log_builtins_filter.h:169
Definition: log_shared.h:194
failure
Definition: log_builtins_filter.h:69
used to identify rules that don&#39;t come from the rule engine, but were injected by the server for emul...
Definition: log_builtins_filter.h:100
action/verb not known/implement by this filter
Definition: log_builtins_filter.h:90
uint32 alloc
maximum number of rules in this ruleset
Definition: log_builtins_filter.h:156
ulong throttle_window_size
for rate-limiting: window-size (in seconds)
Definition: log_builtins_filter.h:133
int32_t int32
Definition: my_inttypes.h:65
Definition: log_builtins_filter.h:105
invalid value
Definition: log_builtins_filter.h:73
enum_log_filter_apply
Definition: log_builtins_filter.h:80
void * filter_data
for ad lib use by said service.
Definition: log_builtins_filter.h:107
Definition: log_builtins_filter.h:110
enum enum_log_filter_verb log_filter_verb
drop this log event
Definition: log_builtins_filter.h:39
#define BEGIN_SERVICE_DEFINITION(name)
don&#39;t know yet
Definition: log_builtins_filter.h:71
Specifies macros to define Service Implementations.
comparator does not exist for this type (yet)
Definition: log_builtins_filter.h:77
struct _log_filter_rule log_filter_rule
enum enum_log_filter_match log_filter_match
Note that if our condition requires absence of the key, and the key does not exist, that constitutes success!
enum_log_builtins_lock
Definition: log_builtins_filter.h:172