7.4.2.6 Rule-Based Error Log Filtering (log_filter_dragnet) — MySQL 9.2

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.';

После настройки параметров фильтрации, рассмотрите возможность присвоения dragnet.log_error_filter_rules с использованием 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 ...
```
Коды ошибок могут быть указаны в числовой форме или в виде соответствующего символического имени ошибки. Например, является символическим именем для ошибки 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 секунд. Оба значения должны быть целочисленными литералами.

Это правило ограничивает сообщения о завершении работы плагина до 5 событий в 60 секунд:
```
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_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

Символ ошибки события как строка (например, ). Значения 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, которое не распознается как имя основного или необязательного поля, считается ссылкой на пользовательское поле.