MySQL :: MySQL 9.0 参考手册 :: 7.4.2.6 基于规则的错误日志过滤 (log_filter_dragnet)

版本 9.0

8.4 当前
8.0

8.0 日语

MySQL 9.0 参考手册 / ... / 基于规则的错误日志过滤 (log_filter_dragnet)

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

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

要启用 log_filter_dragnet 过滤器，请先加载过滤器组件，然后修改 log_error_services 值。以下示例结合内置日志接收器启用 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 来分配 dragnet.log_error_filter_rules，以使设置在服务器重新启动后仍然有效。或者，将设置添加到服务器选项文件。

使用 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 字段和用户定义字段进行比较时才会识别错误符号。

要查找与给定错误代码号相对应的错误符号，请使用以下方法之一

查看服务器错误消息参考中的服务器错误列表。
使用 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 不会将它们解析为相应的数值。此外，拼写错误可能无法检测到，而在 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 规则支持引用错误事件中的核心字段、可选字段和用户定义字段。

核心字段引用

log_filter_dragnet 规则语言的语法中的 log_filter_dragnet 语法命名了过滤器规则识别的核心字段。有关这些字段的一般说明，请参阅第 7.4.2.3 节“错误事件字段”，假定您熟悉这些字段。以下注释仅提供与 log_filter_dragnet 规则中使用的核心字段引用相关的其他信息。

prio

事件优先级，用于指示错误、警告或注释/信息事件。在比较中，每个优先级都可以指定为符号优先级名称或整数字面量。优先级符号仅在与 prio 字段进行比较时才被识别。以下比较是等效的

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

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

事件类型	优先级符号	数字优先级
错误事件	`ERROR`	1
警告事件	`WARNING`	2
注释/信息事件	`INFORMATION`	3

还有一个消息优先级 SYSTEM，但系统消息无法过滤，并且始终写入错误日志。

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

IF prio > WARNING THEN drop.

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

仅错误（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.
```
此规则实际上可以省略，因为没有大于 INFORMATION 的 prio 值，因此实际上它什么也不删除。

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 不会将指定为字符串的比较值解析为等效的数字错误代码。（为此，必须使用其不带引号的符号指定错误。）

可选字段引用

log_filter_dragnet 规则语言的语法中的 log_filter_dragnet 语法命名了过滤器规则识别的可选字段。有关这些字段的一般说明，请参阅第 7.4.2.3 节“错误事件字段”，假定您熟悉这些字段。以下注释仅提供与 log_filter_dragnet 规则中使用的可选字段引用相关的其他信息。

label
与 prio 值相对应的标签，以字符串形式表示。过滤器规则可以更改支持自定义标签的日志接收器的标签。label 值更适用于标识日志输出中的特定行，而不是用于过滤器规则比较，因为 log_filter_dragnet 不会将指定为字符串的比较值解析为等效的数字优先级。
source_file
发生事件的源文件，不带任何前导路径。例如，要测试 sql/gis/distance.cc 文件，请编写如下比较
```
IF source_file == "distance.cc" THEN ...
```

用户定义字段引用

log_filter_dragnet 过滤器规则中任何未被识别为核心字段或可选字段名称的字段名称都将被视为引用用户定义字段。