5.4.2.6 ルールベースのエラーログのフィルタリング (log_filter

5.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 がサーバーの起動時に有効になるように設定するには、セクション5.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_error_verbosity=2 の設定を使用して log_sink_internal フィルタによって実行されるフィルタリングに似ています。

読みやすくするために、ルールを別々の行にリストすることをお薦めします。例:

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

例 2 : このルールは、情報イベントを 60 秒当たり 1 つ以下に制限します:

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

必要に応じてフィルタリング構成を設定したら、SET GLOBAL ではなく SET PERSIST を使用して dragnet.log_error_filter_rules を割り当て、サーバーの再起動後も設定を保持することを検討してください。または、サーバーオプションファイルに設定を追加します。

フィルタリング言語の使用を停止するには、まずエラーロギングコンポーネントのセットから削除します。通常、これはフィルタコンポーネントではなく別のフィルタコンポーネントを使用することを意味します。例:

SET GLOBAL log_error_services = 'log_filter_internal; log_sink_internal';

ここでも、SET GLOBAL ではなく SET PERSIST を使用して、サーバーの再起動後も設定を保持することを検討してください。

次に、フィルタ log_filter_dragnet コンポーネントをアンインストールします:

UNINSTALL COMPONENT 'file://component_log_filter_dragnet';

次の各セクションでは、log_filter_dragnet 操作の側面について詳細に説明します:

log_filter_dragnet Rule Language の文法

次の文法では、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 を使用して、エラー記号を確認します:
```
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
```
エラー記号を数値に置換すると、ルールセットは次のようになります:
```
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 のテストは true で、新しい値は比較条件によってテストできます。
unset: フィールドを破棄します。後続のルールでは、フィールド名に対する EXISTS のテストは false で、フィールドと任意の値の比較は false です。
条件が 1 つのフィールド名のみを参照する特殊なケースでは、unset に続くフィールド名はオプションであり、unset は名前付きフィールドを破棄します。これらのルールは同等です:
```
IF myfield == 2 THEN unset myfield.
IF myfield == 2 THEN unset.
```

log_filter_dragnet ルールのフィールドリファレンス

log_filter_dragnet ルールでは、エラーイベントのコア、オプションおよびユーザー定義フィールドへの参照がサポートされています。

コアフィールドリファレンス

log_filter_dragnet Rule Language の文法の log_filter_dragnet 文法では、フィルタルールが認識するコアフィールドに名前が付けられます。これらのフィールドの一般的な説明は、よく理解していることを前提としたセクション5.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_internal フィルタで許可される各 log_error_verbosity 値と同様の効果を得るための log_filter_dragnet ルールを示しています:

エラーのみ (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'など)。log_filter_dragnet では、文字列として指定された比較値が同等の数値エラーコードに解決されないため、err_symbol 値は、フィルタルール比較で使用するよりもログ出力で特定の行を識別することを目的としています。 (そのためには、引用符で囲まれていないシンボルを使用してエラーを指定する必要があります。)

オプションのフィールドリファレンス

log_filter_dragnet Rule Language の文法の log_filter_dragnet 文法では、フィルタルールで認識されるオプションのフィールドに名前が付けられます。これらのフィールドの一般的な説明は、よく理解していることを前提としたセクション5.4.2.3「エラーイベントフィールド」を参照してください。次の備考は、log_filter_dragnet ルール内で使用されるオプションのフィールド参照に特に関連するため、追加情報のみを提供します。

label
prio 値に対応するラベルを文字列として指定します。フィルタルールでは、カスタムラベルをサポートするログシンクのラベルを変更できます。log_filter_dragnet では、文字列として指定された比較値が同等の数値優先度に解決されないため、label の値は、フィルタルール比較で使用するよりもログ出力で特定の行を識別することを目的としています。
source_file
イベントが発生したソースファイル。先頭にパスはありません。たとえば、sql/gis/distance.cc ファイルをテストするには、次のように比較を記述します:
```
IF source_file == "distance.cc" THEN ...
```

ユーザー定義フィールドリファレンス

コアまたはオプションのフィールド名として認識されない log_filter_dragnet フィルタルール内のフィールド名は、ユーザー定義フィールドを参照するために使用されます。