5.4.2.6 Rule-Based Error Log Filtering基于规则的错误日志筛选 (log_filter_dragnet)

The log_filter_dragnet log filter component enables log filtering based on user-defined rules.log_filter_dragnet日志筛选器组件可根据用户定义的规则进行日志过滤。

To enable the log_filter_dragnet filter, first load the filter component, then modify the log_error_services value. 要启用log_filter_dragnet筛选器，请首先加载筛选器组件，然后修改log_error_services值。The following example enables log_filter_dragnet in combination with the built-in log sink:以下示例结合内置日志接收器启用log_filter_dragnet：

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

To set log_error_services to take effect at server startup, use the instructions at Section 5.4.2.1, “Error Log Configuration”. 要将log_error_services设置为在服务器启动时生效，请使用第5.4.2.1节，“错误日志配置”中的说明。Those instructions apply to other error-logging system variables as well.这些说明也适用于其他错误记录系统变量。

With log_filter_dragnet enabled, define its filter rules by setting the dragnet.log_error_filter_rules system variable. 启用log_filter_dragnet后，通过设置dragnet.log_error_filter_rules系统变量来定义其筛选规则。A rule set consists of zero or more rules, where each rule is an IF statement terminated by a period (.) character. 规则集由零个或多个规则组成，其中每个规则都是以句点（.）字符结尾的IF语句。If the variable value is empty (zero rules), no filtering occurs.如果变量值为空（零规则），则不进行筛选。

Example 1. This rule set drops information events, and, for other events, removes the source_line field:示例1。此规则集删除信息事件，对于其他事件，删除source_line字段：

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

The effect is similar to the filtering performed by the log_sink_internal filter with a setting of log_error_verbosity=2.其效果类似于log_sink_internal筛选器执行的过滤，设置为log_error_verbosity=2。

For readability, you might find it preferable to list the rules on separate lines. For example:为了便于阅读，您可能会发现最好在单独的行中列出规则。例如

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

Example 2: This rule limits information events to no more than one per 60 seconds:示例2：此规则将信息事件限制为每60秒不超过一个：

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

Once you have the filtering configuration set up as you desire, consider assigning dragnet.log_error_filter_rules using SET PERSIST rather than SET GLOBAL to make the setting persist across server restarts. 一旦根据需要设置了筛选配置，请考虑使用SET PERSIST而不是SET GLOBAL分配dragnet.log_error_filter_rules，以使该设置在服务器重新启动时保持不变。Alternatively, add the setting to the server option file.或者，将设置添加到服务器选项文件中。

To stop using the filtering language, first remove it from the set of error logging components. Usually this means using a different filter component rather than no filter component. For example:要停止使用筛选语言，请首先将其从错误日志记录组件集中删除。通常这意味着使用不同的筛选器组件，而不是不使用过滤器组件。例如

SET GLOBAL log_error_services = 'log_filter_internal; log_sink_internal';

Again, consider using using SET PERSIST rather than SET GLOBAL to make the setting persist across server restarts.同样，考虑使用SET PERSIST而不是SET GLOBAL，使设置在服务器重新启动时保持不变。

Then uninstall the filter log_filter_dragnet component:然后卸载filter log_filter_dragnet组件：

UNINSTALL COMPONENT 'file://component_log_filter_dragnet';

The following sections describe aspects of log_filter_dragnet operation in more detail:以下部分更详细地描述了log_filter_dragnet操作的各个方面：

Grammar for log_filter_dragnet Rule Languagelog_filter_dragnet规则语言的语法

The following grammar defines the language for log_filter_dragnet filter rules. 以下语法定义了log_filter_dragnet筛选器规则的语言。Each rule is an IF statement terminated by a period (.) character. 每个规则都是一个以句点（.）字符结尾的IF语句。The language is not case-sensitive.该语言不区分大小写。

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
}

Simple conditions compare a field to a value or test field existence. To construct more complex conditions, use the AND and OR operators. Both operators have the same precedence and evaluate left to right.简单条件将字段与值或测试字段的存在进行比较。要构造更复杂的条件，请使用AND和OR运算符。两个运算符具有相同的优先级，从左到右计算。

To escape a character within a string, precede it by a backslash (\). 若要对字符串中的字符进行转义，请在其前面加一个反斜杠（\）。A backslash is required to include backslash itself or the string-quoting character, optional for other characters.反斜杠必须包含反斜杠本身或字符串引用字符，其他字符可选。

For convenience, log_filter_dragnet supports symbolic names for comparisons to certain fields. For readability and portability, symbolic values are preferable (where applicable) to numeric values.为了方便起见，log_filter_dragnet支持与某些字段进行比较的符号名称。为了可读性和可移植性，符号值比数值更可取（如适用）。

  • Event priority values 1, 2, and 3 can be specified as ERROR, WARNING, and INFORMATION. 事件优先级值1、2和3可以指定为ERROR、WARNING和INFORMATION。Priority symbols are recognized only in comparisons with the prio field. These comparisons are equivalent:只有在与prio字段进行比较时才能识别优先级符号。这些比较是等效的：

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

  • Error codes can be specified in numeric form or as the corresponding error symbol. 错误代码可以以数字形式指定，也可以指定为相应的错误符号。For example, ER_STARTUP is the symbolic name for error 1408, so these comparisons are equivalent:例如，ER_STARTUP是错误1408的符号名称，因此这些比较是等效的：

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

    Error symbols are recognized only in comparisons with the err_code field and user-defined fields.只有在与err_code字段和用户定义字段进行比较时才能识别错误符号。

    To find the error symbol corresponding to a given error code number, use one of these methods:要查找与给定错误代码编号对应的错误符号，请使用以下方法之一：

    • Check the list of server errors at Server Error Message Reference.请查看“服务器错误消息参考”中的服务器错误列表。

    • Use the perror command. 使用perror命令。Given an error number argument, perror displays information about the error, including its symbol.给定一个错误号参数，perror会显示有关错误的信息，包括其符号。

    Suppose that a rule set with error numbers looks like this:假设一个包含错误编号的规则集如下所示：

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

    Using perror, determine the error symbols:使用perror确定错误符号：

    shell> 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

    Substituting error symbols for numbers, the rule set becomes:将错误符号替换为数字，规则集变为：

    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.

Symbolic names can be specified as quoted strings for comparison with string fields, but in such cases the names are strings that have no special meaning and log_filter_dragnet does not resolve them to the corresponding numeric value. 符号名称可以指定为带引号的字符串，以便与字符串字段进行比较，但在这种情况下，名称是没有特殊含义的字符串，并且log_filter_dragnet不会将其解析为相应的数值。Also, typos may go undetected, whereas an error occurs immediately on SET for attempts to use an unquoted symbol unknown to the server.此外，打字错误可能未被检测到，而在SET上尝试使用服务器未知的未加引号的符号时会立即发生错误。

Actions for log_filter_dragnet Ruleslog_filter_dragnet规则的操作

log_filter_dragnet supports these actions in filter rules:log_filter_dragnet在筛选规则中支持以下操作：

  • drop: Drop the current log event (do not log it).：删除当前日志事件（不记录）。

  • throttle: Apply rate limiting to reduce log verbosity for events matching particular conditions. ：应用速率限制以减少与特定条件匹配的事件的日志详细信息。The argument indicates a rate, in the form count or count/window_size. 参数指示速率，格式为count或count/window_size。The count value indicates the permitted number of event occurrences to log per time window. count值表示每个时间窗口允许记录的事件发生次数。The window_size value is the time window in seconds; if omitted, the default window is 60 seconds. Both values must be integer literals.window_size值是以秒为单位的时间窗口；如果省略，默认窗口为60秒。两个值都必须是整数文字。

    This rule throttles plugin-shutdown messages to 5 occurrences per 60 seconds:此规则将插件关闭消息限制为每60秒出现5次：

    IF err_code == ER_PLUGIN_SHUTTING_DOWN_PLUGIN THEN throttle 5.

    This rule throttles errors and warnings to 1000 occurrences per hour and information messages to 100 occurrences per hour:此规则将错误和警告限制为每小时1000次，将信息消息限制为每每小时100次：

    IF prio <= INFORMATION THEN throttle 1000/3600 ELSE throttle 100/3600.

  • set: Assign a value to a field (and cause the field to exist if it did not already). ：为字段分配一个值（如果字段不存在，则使其存在）。In subsequent rules, EXISTS tests against the field name are true, and the new value can be tested by comparison conditions.在随后的规则中，针对字段名的EXISTS测试为true，并且可以通过比较条件来测试新值。

  • unset: Discard a field. In subsequent rules, EXISTS tests against the field name are false, and comparisons of the field against any value are false.：放弃字段。在随后的规则中，针对字段名的EXISTS测试为false，而针对任何值的字段比较为false。

    In the special case that the condition refers to exactly one field name, the field name following unset is optional and unset discards the named field. These rules are equivalent:在条件仅引用一个字段名称的特殊情况下，unset后面的字段名称是可选的，unset将丢弃命名字段。这些规则是等效的：

    IF myfield == 2 THEN unset myfield.
IF myfield == 2 THEN unset.
Field References in log_filter_dragnet Ruleslog_filter_dragnet规则中的字段引用

log_filter_dragnet rules support references to core, optional, and user-defined fields in error events.log_filter_dragnet规则支持在错误事件中引用核心字段、可选字段和用户定义字段。

Core Field References核心字段参考

The log_filter_dragnet grammar at Grammar for log_filter_dragnet Rule Language names the core fields that filter rules recognize. log_filter_dragnet规则语言的grammar中的log_filter_dragnet语法命名了筛选规则可识别的核心字段。For general descriptions of these fields, see Section 5.4.2.3, “Error Event Fields”, with which you are assumed to be familiar. 有关这些字段的一般说明，请参阅第5.4.2.3节，“错误事件字段”，假设您熟悉这些字段。The following remarks provide additional information only as it pertains specifically to core field references as used within log_filter_dragnet rules.以下注释仅提供额外信息，因为它专门涉及log_filter_dragnet规则中使用的核心字段引用。

  • prio

    The event priority, to indicate an error, warning, or note/information event. In comparisons, each priority can be specified as a symbolic priority name or an integer literal. 事件优先级，用于指示错误、警告或备注/信息事件。在比较中，每个优先级可以指定为符号优先级名称或整数文本。Priority symbols are recognized only in comparisons with the prio field. These comparisons are equivalent:只有在与prio字段进行比较时才能识别优先级符号。这些比较是等效的：

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

    The following table shows the permitted priority levels.下表显示了允许的优先级。

    Event TypePriority SymbolNumeric Priority
    Error eventERROR1
    Warning eventWARNING2
    Note/information eventINFORMATION3

    There is also a message priority of SYSTEM, but system messages cannot be filtered and are always written to the error log.还有一个消息优先级为SYSTEM，但系统消息无法筛选，并且总是写入错误日志。

    Priority values follow the principle that higher priorities have lower values, and vice versa. Priority values begin at 1 for the most severe events (errors) and increase for events with decreasing priority. 优先级值遵循的原则是优先级越高，优先级越低，反之亦然。对于最严重的事件（错误），优先级值从1开始，对于优先级降低的事件，优先级值会增加。For example, to discard events with priority lower than warnings, test for priority values higher than WARNING:例如，要丢弃优先级低于警告的事件，请测试优先级值是否高于WARNING：

    IF prio > WARNING THEN drop.

    The following examples show the log_filter_dragnet rules to achieve an effect similar to each log_error_verbosity value permitted by the log_filter_internal filter:以下示例显示了log_filter_dragnet规则，以实现与log_filter_internal筛选器允许的每个log_error_verbosity值类似的效果：

    • Errors only (log_error_verbosity=1):

      IF prio > ERROR THEN drop.

    • Errors and warnings (log_error_verbosity=2):错误和警告（log_error_verbosity=2）：

      IF prio > WARNING THEN drop.

    • Errors, warnings, and notes (log_error_verbosity=3):错误、警告和注释（log_error_verbosity=3）：

      IF prio > INFORMATION THEN drop.

      This rule can actually be omitted because there are no prio values greater than INFORMATION, so effectively it drops nothing.这个规则实际上可以省略，因为没有比INFORMATION大的prio值，所以它实际上什么都不掉。

  • err_code

    The numeric event error code. In comparisons, the value to test can be specified as a symbolic error name or an integer literal. 数字事件错误代码。在比较中，要测试的值可以指定为符号错误名称或整数文本。Error symbols are recognized only in comparisons with the err_code field and user-defined fields. These comparisons are equivalent:只有在与err_code字段和用户定义字段进行比较时才能识别错误符号。这些比较是等效的：

    IF err_code == ER_ACCESS_DENIED_ERROR THEN ...
IF err_code == 1045 THEN ...

  • err_symbol

    The event error symbol, as a string (for example, 'ER_DUP_KEY'). 事件错误符号，作为字符串（例如'ER_DUP_KEY'）。err_symbol values are intended more for identifying particular lines in log output than for use in filter rule comparisons because log_filter_dragnet does not resolve comparison values specified as strings to the equivalent numeric error code. err_symbol值更多地用于识别日志输出中的特定行，而不是用于筛选规则比较，因为log_filter_dragnet不会将指定为字符串的比较值解析为等效的数字错误代码。(For that to occur, an error must be specified using its unquoted symbol.)（若要发生这种情况，必须使用未加引号的符号指定错误。）

Optional Field References可选字段参考

The log_filter_dragnet grammar at Grammar for log_filter_dragnet Rule Language names the optional fields that filter rules recognize. log_filter_dragnet规则语言的grammar处的log_filter_dragnet语法命名了筛选规则可识别的可选字段。For general descriptions of these fields, see Section 5.4.2.3, “Error Event Fields”, with which you are assumed to be familiar. 有关这些字段的一般说明，请参阅第5.4.2.3节，“错误事件字段”，假设您熟悉这些字段。The following remarks provide additional information only as it pertains specifically to optional field references as used within log_filter_dragnet rules.以下注释仅提供附加信息，因为它专门涉及log_filter_dragnet规则中使用的可选字段引用。

  • label

    The label corresponding to the prio value, as a string. Filter rules can change the label for log sinks that support custom labels. 与prio值对应的标签，作为字符串。筛选规则可以更改支持自定义标签的日志接收器的标签。label values are intended more for identifying particular lines in log output than for use in filter rule comparisons because log_filter_dragnet does not resolve comparison values specified as strings to the equivalent numeric priority.label值更多地用于识别日志输出中的特定行，而不是用于筛选规则比较，因为log_filter_dragnet不会将指定为字符串的比较值解析为等效的数字优先级。

  • source_file

    The source file in which the event occurred, without any leading path. For example, to test for the sql/gis/distance.cc file, write the comparison like this:发生事件的源文件，没有任何前导路径。例如，要测试sql/gis/distance.cc文件，请这样写比较：

    IF source_file == "distance.cc" THEN ...
User-Defined Field References用户定义的字段引用

Any field name in a log_filter_dragnet filter rule not recognized as a core or optional field name is taken to refer to a user-defined field.log_filter_dragnet筛选器规则中未被识别为核心或可选字段名称的任何字段名称都被视为引用用户定义的字段。