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