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 測試為 true，並且可以透過比較條件來測試新值。
unset：捨棄欄位。在後續規則中，針對欄位名稱的 EXISTS 測試為 false，並且欄位與任何值的比較都為 false。
在條件恰好參考一個欄位名稱的特殊情況下，unset 後面的欄位名稱是可選的，並且 unset 會捨棄命名的欄位。這些規則是等效的：
```
IF myfield == 2 THEN unset myfield.
IF myfield == 2 THEN unset.
```

`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 規則語言的語法會命名篩選規則可識別的可選欄位。如需這些欄位的一般描述，請參閱第 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 篩選規則中未識別為核心或可選欄位名稱的任何欄位名稱都被視為是指使用者定義的欄位。