若要明確啟用或停用所有事件的記錄，請在篩選器中使用 log 項目

{
  "filter": { "log": true }
}

log 值可以是 true 或 false。

上述篩選器會啟用所有事件的記錄。它等同於

{
  "filter": { }
}

記錄行為取決於 log 值以及是否指定 class 或 event 項目

若要記錄特定類別的事件，請在篩選器中使用 class 項目，其 name 欄位表示要記錄的類別名稱

{
  "filter": {
    "class": { "name": "connection" }
  }
}

name 值可以是 connection、general 或 table_access，分別記錄連線、一般或表格存取事件。

上述篩選器會啟用 connection 類別中事件的記錄。它等同於以下篩選器，其中 log 項目已明確定義

{
  "filter": {
    "log": false,
    "class": { "log": true,
               "name": "connection" }
  }
}

若要啟用多個類別的記錄，請將 class 值定義為 JSON 陣列元素，該元素會命名類別

{
  "filter": {
    "class": [
      { "name": "connection" },
      { "name": "general" },
      { "name": "table_access" }
    ]
  }
}

{
  "filter": {
    "class": [
      { "name": [ "connection", "general", "table_access" ] }
    ]
  }
}

若要選擇特定的事件子類別，請使用包含 name 項目的 event 項目，該 name 項目會命名子類別。由 event 項目選取的事件預設動作是記錄它們。例如，以下篩選器會啟用對已命名事件子類別的記錄：

{
  "filter": {
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect" },
          { "name": "disconnect" }
        ]
      },
      { "name": "general" },
      {
        "name": "table_access",
        "event": [
          { "name": "insert" },
          { "name": "delete" },
          { "name": "update" }
        ]
      }
    ]
  }
}

event 項目也可以包含明確的 log 項目，以指示是否要記錄符合條件的事件。此 event 項目會選擇多個事件，並明確指示它們的記錄行為：

"event": [
  { "name": "read", "log": false },
  { "name": "insert", "log": true },
  { "name": "delete", "log": true },
  { "name": "update", "log": true }
]

如果 event 項目包含 abort 項目，則它也可以指示是否要封鎖符合條件的事件。詳細資訊請參閱封鎖特定事件的執行。

表 8.34，「事件類別和子類別組合」描述了每個事件類別允許的子類別值。

表 8.35，「每個事件類別和子類別組合的記錄和中止特性」描述了每個事件子類別是否可以記錄或中止。

篩選器可以定義為包含式或排除式模式

若要執行包含式記錄，請全域停用記錄，並為特定類別啟用記錄。此篩選器會記錄 connection 類別中的 connect 和 disconnect 事件，以及 general 類別中的事件：

{
  "filter": {
    "log": false,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": true },
          { "name": "disconnect", "log": true }
        ]
      },
      { "name": "general", "log": true }
    ]
  }
}

若要執行排除式記錄，請全域啟用記錄，並為特定類別停用記錄。此篩選器會記錄除了 general 類別中的事件之外的所有內容：

{
  "filter": {
    "log": true,
    "class":
      { "name": "general", "log": false }
  }
}

此篩選器會記錄 connection 類別中的 change_user 事件、message 事件和 table_access 事件，這是由於不記錄其他所有內容而來的：

{
  "filter": {
    "log": true,
    "class": [
      {
        "name": "connection",
        "event": [
          { "name": "connect", "log": false },
          { "name": "disconnect", "log": false }
        ]
      },
      { "name": "general", "log": false }
    ]
  }
}

若要根據特定的事件欄位值啟用記錄，請在 log 項目中指定一個 field 項目，該項目會指示欄位名稱及其預期值：

{
  "filter": {
    "class": {
    "name": "general",
      "event": {
        "name": "status",
        "log": {
          "field": { "name": "general_command.str", "value": "Query" }
        }
      }
    }
  }
}

每個事件都包含事件類別特定的欄位，可以從篩選器內部存取這些欄位來執行自訂篩選。

connection 類別中的事件表示在工作階段期間發生與連線相關的活動時，例如使用者連線到或中斷與伺服器的連線。表 8.36，「連線事件欄位」指示 connection 事件允許的欄位。

"::xxx" 值是符號偽常數，可以取代文字數值。它們必須以字串形式引述，並且區分大小寫。

general 類別中的事件表示操作的狀態代碼及其詳細資訊。表 8.37，「一般事件欄位」指示 general 事件允許的欄位。

general_command.str 指示命令名稱：Query、Execute、Quit 或 Change user。

當 general_command.str 欄位設定為 Query 或 Execute 時，general 事件會包含設定為值的 general_sql_command.str，該值會指定 SQL 命令的類型：alter_db、alter_db_upgrade、admin_commands 等等。可用的 general_sql_command.str 值可以視為此語句顯示的效能架構工具的最後一個組件：

mysql> SELECT NAME FROM performance_schema.setup_instruments
       WHERE NAME LIKE 'statement/sql/%' ORDER BY NAME;
+---------------------------------------+
| NAME                                  |
+---------------------------------------+
| statement/sql/alter_db                |
| statement/sql/alter_db_upgrade        |
| statement/sql/alter_event             |
| statement/sql/alter_function          |
| statement/sql/alter_instance          |
| statement/sql/alter_procedure         |
| statement/sql/alter_server            |
...

table_access 類別中的事件提供有關特定類型資料表存取方式的資訊。表 8.38，「資料表存取事件欄位」指示 table_access 事件允許的欄位。

以下清單顯示哪些語句會產生哪些資料表存取事件：

event 項目可以包含一個 abort 項目，該項目指示是否要防止符合條件的事件執行。abort 允許編寫規則以封鎖特定 SQL 語句的執行。

abort 項目必須出現在 event 項目中。例如：

"event": {
  "name": qualifying event subclass names
  "abort": condition
}

對於由 name 項目選取的事件子類別，abort 動作為 true 或 false，具體取決於 condition 評估結果。如果條件評估為 true，則會封鎖事件。否則，事件會繼續執行。

condition 規格可以像 true 或 false 一樣簡單，或者可以更複雜，以便評估取決於事件特性。

此篩選器會封鎖 INSERT、UPDATE 和 DELETE 陳述式

{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": true
      }
    }
  }
}

此更複雜的篩選器會封鎖相同的陳述式，但僅針對特定資料表 ( finances.bank_account)

{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "insert", "update", "delete" ],
        "abort": {
          "and": [
            { "field": { "name": "table_database.str", "value": "finances" } },
            { "field": { "name": "table_name.str", "value": "bank_account" } }
          ]
        }
      }
    }
  }
}

篩選器比對和封鎖的陳述式會向用戶端傳回錯誤

ERROR 1045 (28000): Statement was aborted by an audit log filter

並非所有事件都可以被封鎖 (請參閱表 8.35，“每個事件類別和子類別組合的記錄和中止特性”)。對於無法被封鎖的事件，稽核日誌會在錯誤日誌中寫入警告，而不是封鎖它。

對於嘗試定義一個篩選器，其中 abort 項目出現在 event 項目以外的其他位置，則會發生錯誤。

邏輯運算子 (and、or、not) 允許建構複雜的條件，以便撰寫更進階的篩選設定。以下 log 項目僅記錄具有特定值和長度的 general_command 欄位的 general 事件

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "or": [
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Query" } },
                { "field": { "name": "general_command.length", "value": 5 } }
              ]
            },
            {
              "and": [
                { "field": { "name": "general_command.str",    "value": "Execute" } },
                { "field": { "name": "general_command.length", "value": 7 } }
              ]
            }
          ]
        }
      }
    }
  }
}

若要在 log 條件中參照預先定義的變數，請使用 variable 項目，該項目會採用 name 和 value 項目，並測試具名變數與給定值是否相等

"variable": {
  "name": "variable_name",
  "value": comparison_value
}

如果 variable_name 的值為 comparison_value，則此條件為真，否則為假。

範例

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "variable": {
            "name": "audit_log_connection_policy_value",
            "value": "::none"
          }
        }
      }
    }
  }
}

每個預先定義的變數都對應於一個系統變數。透過撰寫測試預先定義變數的篩選器，您可以透過設定對應的系統變數來修改篩選器操作，而無需重新定義篩選器。例如，透過撰寫測試 audit_log_connection_policy_value 預先定義變數值的篩選器，您可以透過變更 audit_log_connection_policy 系統變數的值來修改篩選器操作。

audit_log_xxx_policy 系統變數用於已棄用的舊版模式稽核日誌 (請參閱第 8.4.5.10 節，「舊版模式稽核日誌篩選」)。使用基於規則的稽核日誌篩選時，這些變數仍然可見 (例如，使用 SHOW VARIABLES)，但除非您撰寫包含參照這些變數的結構的篩選器，否則變更它們不會有任何效果。

下列清單描述了 variable 項目允許的預先定義變數

若要在 log 條件中參照預先定義的函式，請使用 function 項目，該項目會採用 name 和 args 項目分別指定函式名稱及其引數

"function": {
  "name": "function_name",
  "args": arguments
}

name 項目應僅指定函式名稱，而不要使用括號或引數清單。

args 項目必須滿足以下條件

如果引數的數量不正確或引數不是函式所需的正確資料類型，則會發生錯誤。

範例

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "log": {
          "function": {
            "name": "find_in_include_list",
            "args": [ { "string": [ { "field": "user.str" },
                                    { "string": "@"},
                                    { "field": "host.str" } ] } ]
          }
        }
      }
    }
  }
}

先前的篩選器會根據是否在 audit_log_include_accounts 系統變數中找到目前的用戶來決定是否記錄 general 類別 status 事件。該用戶是使用事件中的欄位建構的。

下列清單描述了 function 項目允許的預先定義函式

稽核篩選器定義支援取代某些稽核事件欄位，以便記錄的事件包含取代值而不是原始值。此功能使記錄的稽核記錄能夠包含陳述式摘要而不是文字陳述式，這對於陳述式可能會暴露敏感值的 MySQL 部署非常有用。

稽核事件中的欄位取代工作方式如下

如表 8.42，“可以取代的事件欄位” 所示，目前唯一可以取代的欄位是包含陳述式文字的欄位 (發生在 general 和 table_access 類別的事件中)。此外，唯一允許用於指定取代值的函式是 query_digest。這表示唯一允許的取代操作是將陳述式文字取代為其對應的摘要。

由於欄位替換發生在早期稽核階段（過濾期間），因此無論之後寫入的日誌格式為何（也就是說，無論稽核日誌外掛程式產生 XML 或 JSON 輸出），選擇寫入陳述式字面文字或摘要值都適用。

欄位替換可以在不同的事件細微度層級進行

在篩選器定義中，透過包含 print 項目來指定欄位替換，其語法如下

"print": {
  "field": {
    "name": "field_name",
    "print": condition,
    "replace": replacement_value
  }
}

在 print 項目中，其 field 項目採用以下三個項目來指示是否以及如何進行替換

例如，此篩選器定義適用於 general 類別中的所有事件，將陳述式字面文字替換為其摘要

{
  "filter": {
    "class": {
      "name": "general",
      "print": {
        "field": {
          "name": "general_query.str",
          "print": false,
          "replace": {
            "function": {
              "name": "query_digest"
            }
          }
        }
      }
    }
  }
}

上述篩選器使用此 print 項目，以無條件將 general_query.str 中包含的陳述式字面文字替換為其摘要值

"print": {
  "field": {
    "name": "general_query.str",
    "print": false,
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}

print 項目可以用不同的方式寫入，以實作不同的替換策略。剛才顯示的 replace 項目使用此 function 結構來指定替換文字，以傳回代表目前陳述式摘要的字串

"function": {
  "name": "query_digest"
}

query_digest 函數也可以用另一種方式使用，作為傳回布林值的比較器，這使其能夠在 print 條件中使用。若要執行此操作，請提供一個引數，指定比較陳述式摘要

"function": {
  "name": "query_digest",
  "args": "digest"
}

在此情況下，query_digest 會根據目前陳述式摘要是否與比較摘要相同而傳回 true 或 false。以這種方式使用 query_digest，可讓篩選器定義偵測與特定摘要相符的陳述式。以下結構中的條件僅對於摘要等於 SELECT ? 的陳述式為 true，因此僅對不符合摘要的陳述式執行替換

"print": {
  "field": {
    "name": "general_query.str",
    "print": {
      "function": {
        "name": "query_digest",
        "args": "SELECT ?"
      }
    },
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}

若要僅對符合摘要的陳述式執行替換，請使用 not 來反轉條件

"print": {
  "field": {
    "name": "general_query.str",
    "print": {
      "not": {
        "function": {
          "name": "query_digest",
          "args": "SELECT ?"
        }
      }
    },
    "replace": {
      "function": {
        "name": "query_digest"
      }
    }
  }
}

假設您希望稽核日誌僅包含陳述式摘要，而不包含字面文字陳述式。若要達成此目的，您必須對包含陳述式文字的所有事件執行替換；也就是說，general 和 table_access 類別中的事件。較早的篩選器定義說明了如何無條件替換 general 事件的陳述式文字。若要對 table_access 事件執行相同的操作，請使用類似的篩選器，但將類別從 general 變更為 table_access，並將欄位名稱從 general_query.str 變更為 query.str

{
  "filter": {
    "class": {
      "name": "table_access",
      "print": {
        "field": {
          "name": "query.str",
          "print": false,
          "replace": {
            "function": {
              "name": "query_digest"
            }
          }
        }
      }
    }
  }
}

合併 general 和 table_access 篩選器會產生一個單一篩選器，該篩選器會對所有包含陳述式文字的事件執行替換

{
  "filter": {
    "class": [
      {
        "name": "general",
        "print": {
          "field": {
            "name": "general_query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      },
      {
        "name": "table_access",
        "print": {
          "field": {
            "name": "query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      }
    ]
  }
}

若要僅對類別中的某些事件執行替換，請將項目新增至篩選器，以更具體地指出何時進行替換。以下篩選器適用於 table_access 類別中的事件，但僅對 insert 和 update 事件執行替換（讓 read 和 delete 事件保持不變）

{
  "filter": {
    "class": {
      "name": "table_access",
      "event": {
        "name": [
          "insert",
          "update"
        ],
        "print": {
          "field": {
            "name": "query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        }
      }
    }
  }
}

此篩選器會對應於所列帳戶管理陳述式的 general 類別事件執行替換（效果是在陳述式中隱藏認證和資料值）

{
  "filter": {
    "class": {
      "name": "general",
      "event": {
        "name": "status",
        "print": {
          "field": {
            "name": "general_query.str",
            "print": false,
            "replace": {
              "function": {
                "name": "query_digest"
              }
            }
          }
        },
        "log": {
          "or": [
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "alter_user"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "alter_user_default_role"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "create_role"
              }
            },
            {
              "field": {
                "name": "general_sql_command.str",
                "value": "create_user"
              }
            }
          ]
        }
      }
    }
  }
}

如需可能的 general_sql_command.str 值相關資訊，請參閱測試事件欄位值。

在某些情況下，可以動態變更篩選器定義。若要執行此操作，請在現有的 filter 中定義 filter 組態。例如

{
  "filter": {
    "id": "main",
    "class": {
      "name": "table_access",
      "event": {
        "name": [ "update", "delete" ],
        "log": false,
        "filter": {
          "class": {
            "name": "general",
            "event" : { "name": "status",
                        "filter": { "ref": "main" } }
          },
          "activate": {
            "or": [
              { "field": { "name": "table_name.str", "value": "temp_1" } },
              { "field": { "name": "table_name.str", "value": "temp_2" } }
            ]
          }
        }
      }
    }
  }
}

當子篩選器中的 activate 項目評估結果為 true 時，就會啟用新的篩選器。不允許在最上層 filter 中使用 activate。

可以使用子篩選器內的 ref 項目來參照原始篩選器的 id，以將新的篩選器替換為原始篩選器。

顯示的篩選器運作方式如下

此篩選器可用於記錄從 temp_1 或 temp_2 資料表更新或刪除任何內容的陳述式，例如以下陳述式

UPDATE temp_1, temp_3 SET temp_1.a=21, temp_3.a=23;

該陳述式會產生多個 table_access 事件，但稽核日誌檔只包含 general / status 項目。