MySQL 8.3.0
Source Code Documentation
log_builtins_filter.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2023, Oracle and/or its affiliates.
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
26#include <atomic>
27
32
33#include "rwlock_scoped_lock.h"
34
35/*
36 services: log item filters
37*/
38
40 LOG_FILTER_UNDEF = 0, /**< not set */
41 LOG_FILTER_DROP = 1, /**< drop this log event */
42 LOG_FILTER_THROTTLE = 2, /**< rate-limit this line class */
43 LOG_FILTER_ITEM_SET = 3, /**< add field */
44 LOG_FILTER_ITEM_DEL = 4, /**< remove field */
45 LOG_FILTER_RETURN = 8, /**< stop filtering, run (next filter or) sinks */
46
47 LOG_FILTER_CHAIN_AND = 4096, /**< no verb yet, part of a condition chain */
48 LOG_FILTER_CHAIN_OR = 4097 /**< no verb yet, part of a condition chain */
50
52 LOG_FILTER_COND_NONE = 0, /**< not set / unconditional */
53 LOG_FILTER_COND_EQ = 1, /**< equal */
54 LOG_FILTER_COND_NE = 2, /**< not equal */
55 LOG_FILTER_COND_LT = 3, /**< less than */
56 LOG_FILTER_COND_LE = 4, /**< less or equal */
57 LOG_FILTER_COND_GE = 5, /**< greater or equal */
58 LOG_FILTER_COND_GT = 6, /**< greater than */
59 LOG_FILTER_COND_PRESENT = 7, /**< field present */
60 LOG_FILTER_COND_ABSENT = 8, /**< field absent */
62
63/**
64 Note that if our condition requires absence of the key, and the
65 key does not exist, that constitutes success!
66*/
68 /** success */
70 /** failure */
72 /** don't know yet */
74 /** invalid value */
76 /** either both or neither operands must be strings */
78 /** comparator does not exist for this type (yet) */
81
83 /** all's well that applies well */
85 /** invalid argument, e.g. "keep -3 characters of this string" */
87 /** log line does not accept further items */
89 /** variant of malloc() failed */
91 /** action/verb not known/implement by this filter */
93 /** had a match for the condition/comparator, but not for the action/verb */
96
98 /** normal state */
100 /** used to identify rules that don't come from the rule engine, but were
101 injected by the server for emulation of legacy log_error_verbosity etc. */
103 /** rule temporarily disabled */
106
107typedef struct _log_filter_tag {
108 const char *filter_name; /**< name of the service that created this rule */
109 void *filter_data; /**< for ad lib use by said service. instance etc. */
111
112typedef struct _log_filter_rule {
113 ulong id; /**< index may change; this will not */
114 ulong jump; /**< default: 0.
115 action of an IF/ELSEIF/ELSE branch:
116 points behind last branch of this
117 IF-construct (we successfully matched
118 a condition, and executed its statement,
119 so leave this IF-construct as nothing
120 else will apply).
121 condition of an IF/ELSEIF:
122 points to next ELSEIF/ELSE, so we can
123 jump there if the condition fails.
124 */
125 log_item match; /**< compare to this item type/class/key/value etc */
126 log_filter_cond cond; /**< how to compare: < > == regex etc */
127 log_filter_verb verb; /**< what to do: drop, upvote, etc */
128 log_item aux; /**< aux: item to add/prio to set/throttle rate */
129
130 // private state keeping
131
132 /** for rate-limiting: at what time will current window end? */
134 /** for rate-limiting: window-size (in seconds) */
136 /** how many lines in this window matched? (both suppressed and not) */
138
139 /** log_filter_flags (fix storage size) */
140 ulong flags;
141
142 /** how often did this rule match? */
143 std::atomic<int32> match_count;
144
145 /** lock an individual rule (to update state keeping) */
147
149 if (this == &other) return *this;
150 id = other.id;
151 jump = other.jump;
152 match = other.match;
153 cond = other.cond;
154 verb = other.verb;
155 aux = other.aux;
159 flags = other.flags;
160 match_count = other.match_count.load();
161 rule_lock = other.rule_lock;
162 return *this;
163 }
165
166#define LOG_FILTER_RULE_MAX 512
167
168typedef struct _log_filter_ruleset {
169 /** creator of this rule */
171
172 /** number of rules currently in ruleset */
174 /** maximum number of rules in this ruleset */
176 /** rules in this ruleset */
178 /**
179 lock for whole ruleset.
180
181 - get a read lock to apply filter rules to event
182 - if a rule changes rule-internal state, like the occurrence count
183 for throttle, it must upgrade to write lock
184 => technically, internal state could use a per-rule lock,
185 but let's keep things simple for now
186 - changing the filter ruleset obviously also needs a write lock
187 */
190
192 LOG_BUILTINS_LOCK_NONE = 0, /**< undefined */
193 LOG_BUILTINS_LOCK_SHARED = 1, /**< read-only lock */
194 LOG_BUILTINS_LOCK_EXCLUSIVE = 2 /**< read-write lock */
196
197BEGIN_SERVICE_DEFINITION(log_builtins_filter)
198// run built-in filter, get/set its configuration
199
200/**
201 Create a new set of filter rules.
202
203 @param tag tag for this ruleset
204 @param count number of rules to allocate
205
206 @retval a pointer to a ruleset structure, or nullptr on failure
207*/
208DECLARE_METHOD(log_filter_ruleset *, filter_ruleset_new,
209 (log_filter_tag * tag, size_t count));
210
211/**
212 Lock and get the filter rules.
213
214 @param ruleset a ruleset (usually allocated with filter_ruleset_new())
215 @param locktype LOG_BUILTINS_LOCK_SHARED lock for reading
216 LOG_BUILTINS_LOCK_EXCLUSIVE lock for writing
217
218 @retval 0 lock acquired
219 @retval !0 failed to acquire lock
220*/
221DECLARE_METHOD(int, filter_ruleset_lock,
222 (log_filter_ruleset * ruleset,
224
225/**
226 Release lock on filter rules.
227
228 @param ruleset a ruleset (usually allocated with filter_ruleset_new())
229*/
230DECLARE_METHOD(void, filter_ruleset_unlock, (log_filter_ruleset * ruleset));
231
232/**
233 Drop an entire filter rule-set. Must hold lock.
234
235 @param ruleset a ruleset * (usually allocated with filter_ruleset_new())
236*/
237DECLARE_METHOD(void, filter_ruleset_drop, (log_filter_ruleset * ruleset));
238
239/**
240 Free an entire filter rule-set. Must hold lock. Lock will be destroyed.
241
242 @param ruleset a ruleset * (usually allocated with filter_ruleset_new())
243 the pointer pointed to will be a nullptr on return.
244*/
245DECLARE_METHOD(void, filter_ruleset_free, (log_filter_ruleset * *ruleset));
246
247/**
248 Move rules from one ruleset to another. Origin will be empty afterwards.
249
250 @param from source ruleset
251 @param to destination ruleset
252*/
253DECLARE_METHOD(int, filter_ruleset_move,
255
256/**
257 Initialize a new rule.
258 This clears the first unused rule. It does not update the rules
259 count; this is for the caller to do if it succeeds in setting up
260 the rule to its satisfaction. If the caller fails, it should
261 log_builtins_filter_rule_free() the incomplete rule.
262
263 @param ruleset a ruleset (usually allocated with filter_ruleset_new())
264
265 @return nullptr: could not initialize rule. Do not call rule_free.
266 !nullptr: the address of the rule. fill in. on success,
267 caller must increase rule count. on failure,
268 it must call rule_free.
269*/
270DECLARE_METHOD(void *, filter_rule_init, (log_filter_ruleset * ruleset));
271
272/**
273 Apply all matching rules from a filter rule set to a given log line.
274
275 @param ll the current log line
276
277 @retval int number of matched rules
278*/
279DECLARE_METHOD(int, filter_run, (log_filter_ruleset * ruleset, log_line *ll));
280
281END_SERVICE_DEFINITION(log_builtins_filter)
282
283/**
284 Temporary primitives for logging services.
285*/
286BEGIN_SERVICE_DEFINITION(log_builtins_filter_debug)
287DECLARE_METHOD(log_filter_ruleset *, filter_debug_ruleset_get, (void));
288END_SERVICE_DEFINITION(log_builtins_filter_debug)
289
290#endif
Specifies macros to define Components.
struct _log_filter_rule log_filter_rule
struct _log_filter_tag log_filter_tag
enum enum_log_builtins_lock log_builtins_filter_lock
enum_log_filter_verb
Definition: log_builtins_filter.h:39
@ LOG_FILTER_ITEM_SET
add field
Definition: log_builtins_filter.h:43
@ LOG_FILTER_UNDEF
not set
Definition: log_builtins_filter.h:40
@ LOG_FILTER_THROTTLE
rate-limit this line class
Definition: log_builtins_filter.h:42
@ LOG_FILTER_RETURN
stop filtering, run (next filter or) sinks
Definition: log_builtins_filter.h:45
@ LOG_FILTER_CHAIN_AND
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:47
@ LOG_FILTER_DROP
drop this log event
Definition: log_builtins_filter.h:41
@ LOG_FILTER_CHAIN_OR
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:48
@ LOG_FILTER_ITEM_DEL
remove field
Definition: log_builtins_filter.h:44
enum enum_log_filter_cond log_filter_cond
struct _log_filter_ruleset log_filter_ruleset
enum_log_filter_cond
Definition: log_builtins_filter.h:51
@ LOG_FILTER_COND_GT
greater than
Definition: log_builtins_filter.h:58
@ LOG_FILTER_COND_NE
not equal
Definition: log_builtins_filter.h:54
@ LOG_FILTER_COND_ABSENT
field absent
Definition: log_builtins_filter.h:60
@ LOG_FILTER_COND_LE
less or equal
Definition: log_builtins_filter.h:56
@ LOG_FILTER_COND_LT
less than
Definition: log_builtins_filter.h:55
@ LOG_FILTER_COND_GE
greater or equal
Definition: log_builtins_filter.h:57
@ LOG_FILTER_COND_NONE
not set / unconditional
Definition: log_builtins_filter.h:52
@ LOG_FILTER_COND_EQ
equal
Definition: log_builtins_filter.h:53
@ LOG_FILTER_COND_PRESENT
field present
Definition: log_builtins_filter.h:59
enum enum_log_filter_match log_filter_match
Note that if our condition requires absence of the key, and the key does not exist,...
#define LOG_FILTER_RULE_MAX
Definition: log_builtins_filter.h:166
enum enum_log_filter_apply log_filter_apply
enum_log_filter_apply
Definition: log_builtins_filter.h:82
@ LOG_FILTER_APPLY_SUCCESS
all's well that applies well
Definition: log_builtins_filter.h:84
@ LOG_FILTER_APPLY_ARGUMENT_OUT_OF_RANGE
invalid argument, e.g.
Definition: log_builtins_filter.h:86
@ LOG_FILTER_APPLY_UNKNOWN_OPERATION
action/verb not known/implement by this filter
Definition: log_builtins_filter.h:92
@ LOG_FILTER_APPLY_OUT_OF_MEMORY
variant of malloc() failed
Definition: log_builtins_filter.h:90
@ LOG_FILTER_APPLY_ITEM_BAG_FULL
log line does not accept further items
Definition: log_builtins_filter.h:88
@ 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:94
enum_log_builtins_lock
Definition: log_builtins_filter.h:191
@ LOG_BUILTINS_LOCK_SHARED
read-only lock
Definition: log_builtins_filter.h:193
@ LOG_BUILTINS_LOCK_NONE
undefined
Definition: log_builtins_filter.h:192
@ LOG_BUILTINS_LOCK_EXCLUSIVE
read-write lock
Definition: log_builtins_filter.h:194
enum enum_log_filter_flags log_filter_flags
enum enum_log_filter_verb log_filter_verb
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:67
@ LOG_FILTER_MATCH_SUCCESS
success
Definition: log_builtins_filter.h:69
@ LOG_FILTER_MATCH_COMPARATOR_UNKNOWN
invalid value
Definition: log_builtins_filter.h:75
@ LOG_FILTER_MATCH_UNSATISFIED
failure
Definition: log_builtins_filter.h:71
@ LOG_FILTER_MATCH_UNCOMPARED
don't know yet
Definition: log_builtins_filter.h:73
@ LOG_FILTER_MATCH_CLASSES_DIFFER
either both or neither operands must be strings
Definition: log_builtins_filter.h:77
@ LOG_FILTER_MATCH_UNSUPPORTED_FOR_TYPE
comparator does not exist for this type (yet)
Definition: log_builtins_filter.h:79
enum_log_filter_flags
Definition: log_builtins_filter.h:97
@ LOG_FILTER_FLAG_NONE
normal state
Definition: log_builtins_filter.h:99
@ LOG_FILTER_FLAG_DISABLED
rule temporarily disabled
Definition: log_builtins_filter.h:104
@ 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:102
unsigned long long int ulonglong
Definition: my_inttypes.h:55
uint32_t uint32
Definition: my_inttypes.h:66
static int count
Definition: myisam_ftdump.cc:44
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
Specifies macros to define Service Implementations.
Definition: log_builtins_filter.h:112
std::atomic< int32 > match_count
how often did this rule match?
Definition: log_builtins_filter.h:143
ulong throttle_matches
how many lines in this window matched? (both suppressed and not)
Definition: log_builtins_filter.h:137
log_item match
compare to this item type/class/key/value etc
Definition: log_builtins_filter.h:125
log_filter_cond cond
how to compare: < > == regex etc
Definition: log_builtins_filter.h:126
ulong jump
default: 0.
Definition: log_builtins_filter.h:114
_log_filter_rule & operator=(const _log_filter_rule &other)
Definition: log_builtins_filter.h:148
log_item aux
aux: item to add/prio to set/throttle rate
Definition: log_builtins_filter.h:128
ulong id
index may change; this will not
Definition: log_builtins_filter.h:113
log_filter_verb verb
what to do: drop, upvote, etc
Definition: log_builtins_filter.h:127
ulonglong throttle_window_end
for rate-limiting: at what time will current window end?
Definition: log_builtins_filter.h:133
mysql_rwlock_t rule_lock
lock an individual rule (to update state keeping)
Definition: log_builtins_filter.h:146
ulong flags
log_filter_flags (fix storage size)
Definition: log_builtins_filter.h:140
ulong throttle_window_size
for rate-limiting: window-size (in seconds)
Definition: log_builtins_filter.h:135
Definition: log_builtins_filter.h:168
log_filter_tag * tag
creator of this rule
Definition: log_builtins_filter.h:170
log_filter_rule rule[LOG_FILTER_RULE_MAX]
rules in this ruleset
Definition: log_builtins_filter.h:177
mysql_rwlock_t ruleset_lock
lock for whole ruleset.
Definition: log_builtins_filter.h:188
uint32 alloc
maximum number of rules in this ruleset
Definition: log_builtins_filter.h:175
uint32 count
number of rules currently in ruleset
Definition: log_builtins_filter.h:173
Definition: log_builtins_filter.h:107
const char * filter_name
name of the service that created this rule
Definition: log_builtins_filter.h:108
void * filter_data
for ad lib use by said service.
Definition: log_builtins_filter.h:109
Definition: log_shared.h:195
log_line ("log event")
Definition: keyring_log_builtins_definition.cc:71
An instrumented rwlock structure.
Definition: mysql_rwlock_bits.h:50