要显式启用或禁用所有事件的日志记录，请在过滤器中使用 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 项，该项命名这些子类。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 事件，其 general_command.str 字段设置为 Query 或 Execute，将包含 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 操作为真或假，具体取决于 condition 的评估。如果该条件的评估结果为真，则该事件将被阻止。否则，该事件将继续执行。

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，“每个事件类别和子类别组合的日志和中止特性”）。对于无法阻止的事件，审核日志会将警告写入错误日志，而不是阻止它。

对于在 event 项目以外的位置出现 abort 项目的过滤器定义尝试，将发生错误。

逻辑运算符 (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 ? 相同摘要的语句为真，因此仅对与摘要不匹配的语句进行替换

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