MySQL :: MySQL 8.4 參考手冊 :: 7.4.2.6 基於規則的錯誤日誌篩選 (log_filter_dragnet)

版本 8.4

9.0
8.0

8.0 日語

MySQL 8.4 參考手冊 / ... / 基於規則的錯誤日誌篩選 (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 規則語言的語法中的 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 過濾規則中的任何欄位名稱，都會被視為參照使用者定義的欄位。

上一個首頁向上下一個