MySQL  8.0.19
Source Code Documentation
log_builtins_filter.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2019, 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) */
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
LOG_FILTER_DROP
@ LOG_FILTER_DROP
drop this log event
Definition: log_builtins_filter.h:39
_log_filter_ruleset::rule
log_filter_rule rule[LOG_FILTER_RULE_MAX]
rules in this ruleset
Definition: log_builtins_filter.h:158
LOG_FILTER_APPLY_UNKNOWN_OPERATION
@ LOG_FILTER_APPLY_UNKNOWN_OPERATION
action/verb not known/implement by this filter
Definition: log_builtins_filter.h:90
_log_filter_rule::verb
log_filter_verb verb
what to do: drop, upvote, etc
Definition: log_builtins_filter.h:125
int32
int32_t int32
Definition: my_inttypes.h:65
END_SERVICE_DEFINITION
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
LOG_FILTER_COND_LE
@ LOG_FILTER_COND_LE
less or equal
Definition: log_builtins_filter.h:54
BEGIN_SERVICE_DEFINITION
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
enum_log_filter_cond
enum_log_filter_cond
Definition: log_builtins_filter.h:49
_log_filter_tag::filter_name
const char * filter_name
name of the service that created this rule
Definition: log_builtins_filter.h:106
LOG_BUILTINS_LOCK_NONE
@ LOG_BUILTINS_LOCK_NONE
undefined
Definition: log_builtins_filter.h:173
LOG_BUILTINS_LOCK_SHARED
@ LOG_BUILTINS_LOCK_SHARED
read-only lock
Definition: log_builtins_filter.h:174
DECLARE_METHOD
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
_log_filter_rule::throttle_window_end
ulonglong throttle_window_end
for rate-limiting: at what time will current window end?
Definition: log_builtins_filter.h:131
mysql_rwlock_t
An instrumented rwlock structure.
Definition: mysql_rwlock_bits.h:50
log_filter_verb
enum enum_log_filter_verb log_filter_verb
LOG_FILTER_COND_LT
@ LOG_FILTER_COND_LT
less than
Definition: log_builtins_filter.h:53
LOG_FILTER_APPLY_TARGET_NOT_IN_LOG_LINE
@ LOG_FILTER_APPLY_TARGET_NOT_IN_LOG_LINE
had a match for the condition/comparator, but not for the action/verb
Definition: log_builtins_filter.h:92
LOG_FILTER_THROTTLE
@ LOG_FILTER_THROTTLE
rate-limit this line class
Definition: log_builtins_filter.h:40
LOG_FILTER_MATCH_SUCCESS
@ LOG_FILTER_MATCH_SUCCESS
success
Definition: log_builtins_filter.h:67
_log_filter_rule::throttle_matches
ulong throttle_matches
how many lines in this window matched? (both suppressed and not)
Definition: log_builtins_filter.h:135
LOG_FILTER_CHAIN_OR
@ LOG_FILTER_CHAIN_OR
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:46
_log_filter_rule::id
ulong id
index may change; this will not
Definition: log_builtins_filter.h:111
enum_log_filter_apply
enum_log_filter_apply
Definition: log_builtins_filter.h:80
_log_item
Definition: log_shared.h:193
LOG_FILTER_COND_PRESENT
@ LOG_FILTER_COND_PRESENT
field present
Definition: log_builtins_filter.h:57
LOG_FILTER_CHAIN_AND
@ LOG_FILTER_CHAIN_AND
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:45
LOG_FILTER_RETURN
@ LOG_FILTER_RETURN
stop filtering, run (next filter or) sinks
Definition: log_builtins_filter.h:43
_log_filter_rule::throttle_window_size
ulong throttle_window_size
for rate-limiting: window-size (in seconds)
Definition: log_builtins_filter.h:133
enum_log_builtins_lock
enum_log_builtins_lock
Definition: log_builtins_filter.h:172
LOG_FILTER_UNDEF
@ LOG_FILTER_UNDEF
not set
Definition: log_builtins_filter.h:38
log_filter_apply
enum enum_log_filter_apply log_filter_apply
LOG_FILTER_FLAG_SYNTHETIC
@ LOG_FILTER_FLAG_SYNTHETIC
used to identify rules that don't come from the rule engine, but were injected by the server for emul...
Definition: log_builtins_filter.h:100
enum_log_filter_verb
enum_log_filter_verb
Definition: log_builtins_filter.h:37
LOG_FILTER_ITEM_SET
@ LOG_FILTER_ITEM_SET
add field
Definition: log_builtins_filter.h:41
log_filter_tag
struct _log_filter_tag log_filter_tag
log_builtins_filter_lock
enum enum_log_builtins_lock log_builtins_filter_lock
LOG_FILTER_MATCH_UNCOMPARED
@ LOG_FILTER_MATCH_UNCOMPARED
don't know yet
Definition: log_builtins_filter.h:71
_log_filter_ruleset
Definition: log_builtins_filter.h:149
LOG_FILTER_APPLY_ARGUMENT_OUT_OF_RANGE
@ LOG_FILTER_APPLY_ARGUMENT_OUT_OF_RANGE
invalid argument, e.g.
Definition: log_builtins_filter.h:84
LOG_FILTER_APPLY_OUT_OF_MEMORY
@ LOG_FILTER_APPLY_OUT_OF_MEMORY
variant of malloc() failed
Definition: log_builtins_filter.h:88
enum_log_filter_match
enum_log_filter_match
Note that if our condition requires absence of the key, and the key does not exist,...
Definition: log_builtins_filter.h:65
LOG_FILTER_APPLY_SUCCESS
@ LOG_FILTER_APPLY_SUCCESS
all's well that applies well
Definition: log_builtins_filter.h:82
LOG_FILTER_APPLY_ITEM_BAG_FULL
@ LOG_FILTER_APPLY_ITEM_BAG_FULL
log line does not accept further items
Definition: log_builtins_filter.h:86
LOG_FILTER_COND_GT
@ LOG_FILTER_COND_GT
greater than
Definition: log_builtins_filter.h:56
component_implementation.h
log_filter_ruleset
struct _log_filter_ruleset log_filter_ruleset
log_filter_rule
struct _log_filter_rule log_filter_rule
uint32
uint32_t uint32
Definition: my_inttypes.h:66
LOG_FILTER_COND_NONE
@ LOG_FILTER_COND_NONE
not set / unconditional
Definition: log_builtins_filter.h:50
_log_filter_ruleset::tag
log_filter_tag * tag
creator of this rule
Definition: log_builtins_filter.h:151
LOG_FILTER_COND_EQ
@ LOG_FILTER_COND_EQ
equal
Definition: log_builtins_filter.h:51
_log_filter_ruleset::count
uint32 count
number of rules currently in ruleset
Definition: log_builtins_filter.h:154
_log_filter_rule::rule_lock
mysql_rwlock_t rule_lock
lock an individual rule (to update state keeping)
Definition: log_builtins_filter.h:144
LOG_FILTER_MATCH_UNSUPPORTED_FOR_TYPE
@ LOG_FILTER_MATCH_UNSUPPORTED_FOR_TYPE
comparator does not exist for this type (yet)
Definition: log_builtins_filter.h:77
_log_filter_rule::cond
log_filter_cond cond
how to compare: < > == regex etc
Definition: log_builtins_filter.h:124
_log_filter_rule
Definition: log_builtins_filter.h:110
enum_log_filter_flags
enum_log_filter_flags
Definition: log_builtins_filter.h:95
_log_filter_rule::jump
ulong jump
default: 0.
Definition: log_builtins_filter.h:112
_log_filter_ruleset::alloc
uint32 alloc
maximum number of rules in this ruleset
Definition: log_builtins_filter.h:156
_log_filter_rule::flags
ulong flags
log_filter_flags (fix storage size)
Definition: log_builtins_filter.h:138
LOG_FILTER_RULE_MAX
#define LOG_FILTER_RULE_MAX
Definition: log_builtins_filter.h:147
log_filter_flags
enum enum_log_filter_flags log_filter_flags
count
ssize_t count
Definition: memcached.c:386
_log_filter_rule::match_count
volatile int32 match_count
how often did this rule match?
Definition: log_builtins_filter.h:141
LOG_FILTER_MATCH_COMPARATOR_UNKNOWN
@ LOG_FILTER_MATCH_COMPARATOR_UNKNOWN
invalid value
Definition: log_builtins_filter.h:73
LOG_BUILTINS_LOCK_EXCLUSIVE
@ LOG_BUILTINS_LOCK_EXCLUSIVE
read-write lock
Definition: log_builtins_filter.h:175
log_filter_cond
enum enum_log_filter_cond log_filter_cond
ulong
unsigned long ulong
Definition: my_inttypes.h:48
ulonglong
unsigned long long int ulonglong
Definition: my_inttypes.h:55
_log_line
log_line ("log event")
Definition: log_builtins_imp.h:126
LOG_FILTER_ITEM_DEL
@ LOG_FILTER_ITEM_DEL
remove field
Definition: log_builtins_filter.h:42
log_shared.h
LOG_FILTER_FLAG_NONE
@ LOG_FILTER_FLAG_NONE
normal state
Definition: log_builtins_filter.h:97
LOG_FILTER_MATCH_UNSATISFIED
@ LOG_FILTER_MATCH_UNSATISFIED
failure
Definition: log_builtins_filter.h:69
LOG_FILTER_MATCH_CLASSES_DIFFER
@ LOG_FILTER_MATCH_CLASSES_DIFFER
either both or neither operands must be strings
Definition: log_builtins_filter.h:75
rwlock_scoped_lock.h
_log_filter_ruleset::ruleset_lock
mysql_rwlock_t ruleset_lock
lock for whole ruleset.
Definition: log_builtins_filter.h:169
LOG_FILTER_COND_ABSENT
@ LOG_FILTER_COND_ABSENT
field absent
Definition: log_builtins_filter.h:58
_log_filter_tag::filter_data
void * filter_data
for ad lib use by said service.
Definition: log_builtins_filter.h:107
LOG_FILTER_FLAG_DISABLED
@ LOG_FILTER_FLAG_DISABLED
rule temporarily disabled
Definition: log_builtins_filter.h:102
_log_filter_rule::match
log_item match
compare to this item type/class/key/value etc
Definition: log_builtins_filter.h:123
LOG_FILTER_COND_GE
@ LOG_FILTER_COND_GE
greater or equal
Definition: log_builtins_filter.h:55
LOG_FILTER_COND_NE
@ LOG_FILTER_COND_NE
not equal
Definition: log_builtins_filter.h:52
_log_filter_rule::aux
log_item aux
aux: item to add/prio to set/throttle rate
Definition: log_builtins_filter.h:126
service_implementation.h
log_filter_match
enum enum_log_filter_match log_filter_match
Note that if our condition requires absence of the key, and the key does not exist,...
my_service.h
_log_filter_tag
Definition: log_builtins_filter.h:105