若要明確啟用或停用記錄所有事件，請在篩選器中使用 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.35，「事件類別和子類別組合」說明每個事件類別允許的子類別值。

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

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

若要執行包含式記錄，請全域停用記錄功能，並為特定類別啟用記錄功能。此篩選器會記錄 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.37，「連線事件欄位」表示 connection 事件允許的欄位。

"::xxx" 值是符號偽常數，可以給定而不是文字數值。它們必須以字串形式引號，且區分大小寫。

general 類別中的事件表示操作的狀態碼及其詳細資料。表 8.38，「一般事件欄位」表示 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 值視為此語句顯示的 Performance Schema 工具的最後組件：

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.39，「資料表存取事件欄位」表示 table_access 事件允許的欄位。

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

event 項目可以包含 abort 項目，此項目指示是否要防止符合條件的事件執行。abort 啟用規則的撰寫，可以封鎖特定 SQL 語句的執行。

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

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

對於由 name 項目選取的事件子類別，abort 動作會根據 condition 的評估結果為 true 或 false。如果條件評估結果為 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.36，「每個事件類別和子類別組合的記錄和中止特性」）。對於無法封鎖的事件，稽核日誌會在錯誤日誌中寫入警告，而不是封鎖它。

對於嘗試定義 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，則為 true，否則為 false。

範例

{
  "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.43，「可替換的事件欄位」所示，目前唯一可替換的欄位是那些包含陳述式文字的欄位（發生在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 ?的陳述式為真，因此僅對不符合摘要的陳述式執行替換

"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項目。