MySQL 8.0.31
Source Code Documentation
log_builtins_filter.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2022, 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
30
31#include "rwlock_scoped_lock.h"
32
33/*
34 services: log item filters
35*/
36
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
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*/
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
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
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
105typedef 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
110typedef 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? */
142
143 /** lock an individual rule (to update state keeping) */
146
147#define LOG_FILTER_RULE_MAX 512
148
149typedef 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
178BEGIN_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*/
189DECLARE_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*/
202DECLARE_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*/
211DECLARE_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*/
218DECLARE_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*/
226DECLARE_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*/
234DECLARE_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*/
251DECLARE_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*/
260DECLARE_METHOD(int, filter_run, (log_filter_ruleset * ruleset, log_line *ll));
261
262END_SERVICE_DEFINITION(log_builtins_filter)
263
264/**
265 Temporary primitives for logging services.
266*/
267BEGIN_SERVICE_DEFINITION(log_builtins_filter_debug)
268DECLARE_METHOD(log_filter_ruleset *, filter_debug_ruleset_get, (void));
269END_SERVICE_DEFINITION(log_builtins_filter_debug)
270
271#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:37
@ LOG_FILTER_ITEM_SET
add field
Definition: log_builtins_filter.h:41
@ LOG_FILTER_UNDEF
not set
Definition: log_builtins_filter.h:38
@ LOG_FILTER_THROTTLE
rate-limit this line class
Definition: log_builtins_filter.h:40
@ LOG_FILTER_RETURN
stop filtering, run (next filter or) sinks
Definition: log_builtins_filter.h:43
@ LOG_FILTER_CHAIN_AND
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:45
@ LOG_FILTER_DROP
drop this log event
Definition: log_builtins_filter.h:39
@ LOG_FILTER_CHAIN_OR
no verb yet, part of a condition chain
Definition: log_builtins_filter.h:46
@ LOG_FILTER_ITEM_DEL
remove field
Definition: log_builtins_filter.h:42
enum enum_log_filter_cond log_filter_cond
struct _log_filter_ruleset log_filter_ruleset
enum_log_filter_cond
Definition: log_builtins_filter.h:49
@ LOG_FILTER_COND_GT
greater than
Definition: log_builtins_filter.h:56
@ LOG_FILTER_COND_NE
not equal
Definition: log_builtins_filter.h:52
@ LOG_FILTER_COND_ABSENT
field absent
Definition: log_builtins_filter.h:58
@ LOG_FILTER_COND_LE
less or equal
Definition: log_builtins_filter.h:54
@ LOG_FILTER_COND_LT
less than
Definition: log_builtins_filter.h:53
@ LOG_FILTER_COND_GE
greater or equal
Definition: log_builtins_filter.h:55
@ LOG_FILTER_COND_NONE
not set / unconditional
Definition: log_builtins_filter.h:50
@ LOG_FILTER_COND_EQ
equal
Definition: log_builtins_filter.h:51
@ LOG_FILTER_COND_PRESENT
field present
Definition: log_builtins_filter.h:57
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:147
enum enum_log_filter_apply log_filter_apply
enum_log_filter_apply
Definition: log_builtins_filter.h:80
@ LOG_FILTER_APPLY_SUCCESS
all's well that applies well
Definition: log_builtins_filter.h:82
@ LOG_FILTER_APPLY_ARGUMENT_OUT_OF_RANGE
invalid argument, e.g.
Definition: log_builtins_filter.h:84
@ LOG_FILTER_APPLY_UNKNOWN_OPERATION
action/verb not known/implement by this filter
Definition: log_builtins_filter.h:90
@ LOG_FILTER_APPLY_OUT_OF_MEMORY
variant of malloc() failed
Definition: log_builtins_filter.h:88
@ LOG_FILTER_APPLY_ITEM_BAG_FULL
log line does not accept further items
Definition: log_builtins_filter.h:86
@ 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
enum_log_builtins_lock
Definition: log_builtins_filter.h:172
@ LOG_BUILTINS_LOCK_SHARED
read-only lock
Definition: log_builtins_filter.h:174
@ LOG_BUILTINS_LOCK_NONE
undefined
Definition: log_builtins_filter.h:173
@ LOG_BUILTINS_LOCK_EXCLUSIVE
read-write lock
Definition: log_builtins_filter.h:175
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:65
@ LOG_FILTER_MATCH_SUCCESS
success
Definition: log_builtins_filter.h:67
@ LOG_FILTER_MATCH_COMPARATOR_UNKNOWN
invalid value
Definition: log_builtins_filter.h:73
@ LOG_FILTER_MATCH_UNSATISFIED
failure
Definition: log_builtins_filter.h:69
@ LOG_FILTER_MATCH_UNCOMPARED
don't know yet
Definition: log_builtins_filter.h:71
@ LOG_FILTER_MATCH_CLASSES_DIFFER
either both or neither operands must be strings
Definition: log_builtins_filter.h:75
@ LOG_FILTER_MATCH_UNSUPPORTED_FOR_TYPE
comparator does not exist for this type (yet)
Definition: log_builtins_filter.h:77
enum_log_filter_flags
Definition: log_builtins_filter.h:95
@ LOG_FILTER_FLAG_NONE
normal state
Definition: log_builtins_filter.h:97
@ LOG_FILTER_FLAG_DISABLED
rule temporarily disabled
Definition: log_builtins_filter.h:102
@ 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
unsigned long long int ulonglong
Definition: my_inttypes.h:55
int32_t int32
Definition: my_inttypes.h:65
uint32_t uint32
Definition: my_inttypes.h:66
static int count
Definition: myisam_ftdump.cc:42
#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:110
ulong throttle_matches
how many lines in this window matched? (both suppressed and not)
Definition: log_builtins_filter.h:135
log_item match
compare to this item type/class/key/value etc
Definition: log_builtins_filter.h:123
log_filter_cond cond
how to compare: < > == regex etc
Definition: log_builtins_filter.h:124
ulong jump
default: 0.
Definition: log_builtins_filter.h:112
log_item aux
aux: item to add/prio to set/throttle rate
Definition: log_builtins_filter.h:126
ulong id
index may change; this will not
Definition: log_builtins_filter.h:111
log_filter_verb verb
what to do: drop, upvote, etc
Definition: log_builtins_filter.h:125
ulonglong throttle_window_end
for rate-limiting: at what time will current window end?
Definition: log_builtins_filter.h:131
mysql_rwlock_t rule_lock
lock an individual rule (to update state keeping)
Definition: log_builtins_filter.h:144
ulong flags
log_filter_flags (fix storage size)
Definition: log_builtins_filter.h:138
volatile int32 match_count
how often did this rule match?
Definition: log_builtins_filter.h:141
ulong throttle_window_size
for rate-limiting: window-size (in seconds)
Definition: log_builtins_filter.h:133
Definition: log_builtins_filter.h:149
log_filter_tag * tag
creator of this rule
Definition: log_builtins_filter.h:151
log_filter_rule rule[LOG_FILTER_RULE_MAX]
rules in this ruleset
Definition: log_builtins_filter.h:158
mysql_rwlock_t ruleset_lock
lock for whole ruleset.
Definition: log_builtins_filter.h:169
uint32 alloc
maximum number of rules in this ruleset
Definition: log_builtins_filter.h:156
uint32 count
number of rules currently in ruleset
Definition: log_builtins_filter.h:154
Definition: log_builtins_filter.h:105
const char * filter_name
name of the service that created this rule
Definition: log_builtins_filter.h:106
void * filter_data
for ad lib use by said service.
Definition: log_builtins_filter.h:107
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