MySQL :: MySQL 8.3 Reference Manual :: 7.4.2.6 Rule-Based Error Log Filtering (log_filter

version 8.3

8.0 current

8.0 Japanese

MySQL 8.3 Reference Manual / ... / Rule-Based Error Log Filtering (log_filter_dragnet)

7.4.2.6 基于规则的错误日志过滤 (log_filter_dragnet)

该 log_filter_dragnet 日志过滤器组件启用基于用户定义规则的日志过滤。

要启用 log_filter_dragnet 过滤器，首先加载过滤器组件，然后修改 log_error_services 值。以下示例在与内置日志 sink 结合使用时启用 log_filter_dragnet：

INSTALL COMPONENT 'file://component_log_filter_dragnet';
SET GLOBAL log_error_services = 'log_filter_dragnet; log_sink_internal';

要使 log_error_services 在服务器启动时生效，请按照第 7.4.2.1 节“错误日志配置” 中的说明进行操作。这些说明也适用于其他错误日志系统变量。

启用 log_filter_dragnet 后，通过设置 dragnet.log_error_filter_rules 系统变量来定义其过滤规则。规则集由零个或多个规则组成，每个规则是一个以句点 (.) 字符结尾的 IF 语句。如果变量值为空（零规则），则不进行过滤。

示例 1. 该规则集删除信息事件，并删除其他事件的 source_line 字段：

SET GLOBAL dragnet.log_error_filter_rules =
  'IF prio>=INFORMATION THEN drop. IF EXISTS source_line THEN unset source_line.';

该效果类似于使用 log_sink_internal 过滤器时的 log_error_verbosity=2 设置。

为了提高可读性，您可能更喜欢将规则列在单独的行上。例如：

SET GLOBAL dragnet.log_error_filter_rules = '
  IF prio>=INFORMATION THEN drop.
  IF EXISTS source_line THEN unset source_line.
';

示例 2：该规则限制信息事件的频率为每 60 秒一次：

SET GLOBAL dragnet.log_error_filter_rules =
  'IF prio>=INFORMATION THEN throttle 1/60.';

一旦您设置了所需的过滤配置，考虑使用 SET PERSIST 而不是 SET GLOBAL 使设置在服务器重启时保持不变。或者，将设置添加到服务器选项文件中。

使用 log_filter_dragnet 时，log_error_suppression_list 将被忽略。

要停止使用过滤语言，首先从错误日志组件集中删除它。通常这意味着使用不同的过滤器组件，而不是不使用过滤器组件。例如：

SET GLOBAL log_error_services = 'log_filter_internal; log_sink_internal';

再次，考虑使用 SET PERSIST 而不是 SET GLOBAL 使设置在服务器重启时保持不变。

然后卸载 log_filter_dragnet 过滤器组件：

UNINSTALL COMPONENT 'file://component_log_filter_dragnet';

以下部分详细描述了 log_filter_dragnet 操作的其他方面：

log_filter_dragnet 规则语言语法

以下语法定义了 log_filter_dragnet 过滤器规则语言。每个规则是一个以句点 (.) 字符结尾的 IF 语句。该语言不区分大小写。

rule:
    IF condition THEN action
    [ELSEIF condition THEN action] ...
    [ELSE action]
    .

condition: {
    field comparator value
  | [NOT] EXISTS field
  | condition {AND | OR}  condition
}

action: {
    drop
  | throttle {count | count / window_size}
  | set field [:= | =] value
  | unset [field]
}

field: {
    core_field
  | optional_field
  | user_defined_field
}

core_field: {
    time
  | msg
  | prio
  | err_code
  | err_symbol
  | SQL_state
  | subsystem
}

optional_field: {
    OS_errno
  | OS_errmsg
  | label
  | user
  | host
  | thread
  | query_id
  | source_file
  | source_line
  | function
  | component
}

user_defined_field:
    sequence of characters in [a-zA-Z0-9_] class

comparator: {== | != | <> | >= | => | <= | =< | < | >}

value: {
    string_literal
  | integer_literal
  | float_literal
  | error_symbol
  | priority
}

count: integer_literal
window_size: integer_literal

string_literal:
    sequence of characters quoted as '...' or "..."

integer_literal:
    sequence of characters in [0-9] class

float_literal:
    integer_literal[.integer_literal]

error_symbol:
    valid MySQL error symbol such as ER_ACCESS_DENIED_ERROR or ER_STARTUP

priority: {
    ERROR
  | WARNING
  | INFORMATION
}

简单条件比较字段与值或测试字段存在。要构建更复杂的条件，请使用 AND 和 OR 运算符。两个运算符具有相同的优先级，并从左到右评估。

要在字符串中转义字符，请在其前面加上反斜杠 (\)。反斜杠是包括反斜杠本身或字符串引号字符在内的其他字符的可选项。

为了方便，log_filter_dragnet 支持某些字段的符号名称比较。为了可读性和可移植性，符号值优先于数字值（在适用情况下）.

事件优先级值 1、2 和 3 可以指定为 ERROR、WARNING 和 INFORMATION。优先级符号仅在与 prio 字段的比较中识别。这些比较是等效的：
```
IF prio == INFORMATION THEN ...
IF prio == 3 THEN ...
```

错误代码可以以数字形式或对应的错误符号指定。例如，ER_STARTUP 是错误 1408 的符号名称，因此这些比较是等效的：

IF err_code == ER_STARTUP THEN ...
IF err_code == 1408 THEN ...

错误符号仅在与 err_code 字段和用户定义字段的比较中识别。

要找到给定错误代码号对应的错误符号，请使用以下方法：

检查服务器错误列表 Server Error Message Reference。
使用 perror 命令。给定错误号参数，perror 显示错误信息，包括其符号。

假设规则集具有错误号码如下：

IF err_code == 10927 OR err_code == 10914 THEN drop.
IF err_code == 1131 THEN drop.

使用 perror，确定错误符号：

$> perror 10927 10914 1131
MySQL error code MY-010927 (ER_ACCESS_DENIED_FOR_USER_ACCOUNT_LOCKED):
Access denied for user '%-.48s'@'%-.64s'. Account is locked.
MySQL error code MY-010914 (ER_ABORTING_USER_CONNECTION):
Aborted connection %u to db: '%-.192s' user: '%-.48s' host:
'%-.64s' (%-.64s).
MySQL error code MY-001131 (ER_PASSWORD_ANONYMOUS_USER):
You are using MySQL as an anonymous user and anonymous users
are not allowed to change passwords

将错误符号代替数字，规则集变为：

IF err_code == ER_ACCESS_DENIED_FOR_USER_ACCOUNT_LOCKED
  OR err_code == ER_ABORTING_USER_CONNECTION THEN drop.
IF err_code == ER_PASSWORD_ANONYMOUS_USER THEN drop.

符号名称可以作为字符串比较与字符串字段，但在这种情况下，名称是字符串，log_filter_dragnet 不会将其解析为对应的数字值。此外，typo 可能不会被检测到，而在 SET 中尝试使用未知服务器符号时，错误将立即发生。

log_filter_dragnet 规则操作

log_filter_dragnet 支持以下操作在过滤规则中：

drop：删除当前日志事件（不记录）。
throttle：应用速率限制以减少日志冗长度，事件匹配特定条件。参数表示速率，形式为 count 或 count/window_size。count 值表示每个时间窗口中允许的事件发生次数。window_size 值是时间窗口的秒数；如果省略，默认窗口为 60 秒。两个值必须是整数文字。

该规则将插件关闭消息限制为每 60 秒 5 次：
```
IF err_code == ER_PLUGIN_SHUTTING_DOWN_PLUGIN THEN throttle 5.
```
该规则将错误和警告限制为每小时 1000 次，信息消息限制为每小时 100 次：
```
IF prio <= INFORMATION THEN throttle 1000/3600 ELSE throttle 100/3600.
```
set：将值分配给字段（并在字段不存在时创建）。在后续规则中，EXISTS 测试字段名称为真，新值可以通过比较条件测试。
unset：丢弃字段。在后续规则中，EXISTS 测试字段名称为假，字段与任何值的比较为假。

在特殊情况下，条件仅引用一个字段名称时，字段名称在 unset 后是可选的，unset 丢弃命名字段。这些规则是等效的：
```
IF myfield == 2 THEN unset myfield.
IF myfield == 2 THEN unset.
```

log_filter_dragnet 规则中的字段引用

log_filter_dragnet 规则支持核心、可选和用户定义字段在错误事件中的引用。

Core Field References

该 log_filter_dragnet 语法在 Grammar for log_filter_dragnet Rule Language 中命名了核心字段，过滤规则识别这些字段。对于这些字段的一般描述，请参阅第 7.4.2.3 节，“错误事件字段”，假设您已经熟悉这些字段。以下备注仅提供了关于核心字段引用在 log_filter_dragnet 规则中的附加信息。

prio

事件优先级，以指示错误、警告或注意/信息事件。在比较中，每个优先级可以指定为符号优先级名称或整数文字。优先级符号仅在 prio 字段的比较中被识别。这些比较是等效的：

IF prio == INFORMATION THEN ...
IF prio == 3 THEN ...

以下表格显示了允许的优先级级别。

Event Type	Priority Symbol	Numeric Priority
Error event	`ERROR`	1
Warning event	`WARNING`	2
Note/information event	`INFORMATION`	3

还有一个消息优先级 SYSTEM，但系统消息不能被过滤并总是写入错误日志。

优先级值遵循高优先级对应低值，反之亦然。优先级值从 1 开始，对应最严重的事件（错误），并随着事件优先级的降低而增加。例如，要丢弃优先级低于警告的事件，可以测试优先级值高于 WARNING：

IF prio > WARNING THEN drop.

以下示例显示了 log_filter_dragnet 规则，以实现类似于每个 log_error_verbosity 值的效果，允许由 log_filter_internal 过滤器：

仅错误 (log_error_verbosity=1):
```
IF prio > ERROR THEN drop.
```
错误和警告 (log_error_verbosity=2):
```
IF prio > WARNING THEN drop.
```
错误、警告和注意 (log_error_verbosity=3):
```
IF prio > INFORMATION THEN drop.
```
这个规则实际上可以省略，因为没有 prio 值大于 INFORMATION，因此实际上什么都不删除。

err_code

事件错误代码。在比较中，可以将要测试的值指定为符号错误名称或整数文字。错误符号仅在 err_code 字段和用户定义字段的比较中被识别。这些比较是等效的：
```
IF err_code == ER_ACCESS_DENIED_ERROR THEN ...
IF err_code == 1045 THEN ...
```
err_symbol

事件错误符号，作为字符串（例如，'ER_DUP_KEY'）。 err_symbol 值主要用于标识日志输出中的特定行，而不是用于过滤规则比较，因为 log_filter_dragnet 不会将字符串指定的比较值解析为等效的数字错误代码。（要发生这种情况，错误必须使用未引用的符号指定。）

Optional Field References

该 log_filter_dragnet 语法在 Grammar for log_filter_dragnet Rule Language 中命名了可选字段，过滤规则识别这些字段。对于这些字段的一般描述，请参阅第 7.4.2.3 节，“错误事件字段”，假设您已经熟悉这些字段。以下备注仅提供了关于可选字段引用在 log_filter_dragnet 规则中的附加信息。

label

对应于 prio 值的标签，作为字符串。过滤规则可以更改支持自定义标签的日志 sink 的标签。 label 值主要用于标识日志输出中的特定行，而不是用于过滤规则比较，因为 log_filter_dragnet 不会将字符串指定的比较值解析为等效的数字优先级。
source_file

事件发生的源文件，without any leading path。例如，要测试 sql/gis/distance.cc 文件，可以这样写比较：
```
IF source_file == "distance.cc" THEN ...
```

User-Defined Field References

任何在 log_filter_dragnet 过滤规则中的字段名称，如果不被识别为核心字段或可选字段名称，则被认为是用户定义字段。

PREV HOME UP NEXT