要显式启用或禁用所有事件的日志记录，请在过滤器中使用 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.35，“事件类和子类组合”描述了每个事件类允许的子类值。

表 8.36，“每个事件类和子类组合的日志和中止特性”描述了每个事件子类是否可以记录或中止。

可以在包含式或排除式模式下定义过滤器

要执行包含式日志记录，请全局禁用日志记录并为特定类启用日志记录。此过滤器记录 连接 类中的 连接 和 断开连接 事件，以及 常规 类中的事件

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

要执行排除式日志记录，请全局启用日志记录并为特定类禁用日志记录。此过滤器记录除 常规 类中的事件之外的所有内容

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

此过滤器记录 连接 类中的 更改用户 事件、消息 事件和 表访问 事件，这是因为它不 记录其他所有内容

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

要根据特定事件字段值启用日志记录，请在 日志 项目中指定一个 字段 项目，该项目指示字段名称及其预期值

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

每个事件都包含特定于事件类的字段，可以从过滤器内部访问这些字段以执行自定义过滤。

连接 类中的事件指示会话期间何时发生与连接相关的活动，例如用户连接到服务器或与服务器断开连接。表 8.37，“连接事件字段” 指示 连接 事件的允许字段。

"::xxx" 值是符号伪常量，可以代替文字数值给出。它们必须用引号括起来，并且区分大小写。

常规 类中的事件指示操作的状态代码及其详细信息。表 8.38，“常规事件字段” 指示 常规 事件的允许字段。

general_command.str 指示命令名称：查询、执行、退出 或 更改用户。

general_command.str 字段设置为 查询 或 执行 的 常规 事件包含设置为指定 SQL 命令类型的值的 general_sql_command.str：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            |
...

表访问 类中的事件提供有关对表的特定访问类型的信息。表 8.39，“表访问事件字段” 指示 表访问 事件的允许字段。

以下列表显示了哪些语句会产生哪些表访问事件

事件 项目可以包含一个 中止 项目，该项目指示是否阻止符合条件的事件执行。中止 允许编写阻止特定 SQL 语句执行的规则。

中止 项目必须出现在 事件 项目中。例如

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

对于 名称 项目选择的事件子类，中止 操作为 true 或 false，具体取决于 条件 求值。如果条件的计算结果为 true，则该事件将被阻止。否则，该事件将继续执行。

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

对于尝试定义 中止 项目出现在 事件 项目之外的过滤器，会发生错误。

逻辑运算符（和、或、非）允许构造复杂的条件，从而能够编写更高级的过滤配置。以下 日志 项目仅记录 general_command 字段具有特定值和长度的 常规 事件

{
  "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 } }
              ]
            }
          ]
        }
      }
    }
  }
}

要引用 日志 条件中的预定义变量，请使用 变量 项目，该项目采用 名称 和 值 项目，并测试命名变量与给定值是否相等

"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 ? 的语句为 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 条目。