要明确启用或禁用所有事件的日志记录，请在过滤器中使用 log 项：

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

log 值可以是 true 或 false。

前面的过滤器启用了所有事件的日志记录。它等同于：

{
  "filter": { }
}

日志记录行为取决于 log 值和是否指定了 class 或 event 项：

要记录特定类的事件，请在过滤器中使用 class 项，其中的 name 字段指定要记录的类的名称：

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

名称值可以是 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 项，命名要记录的子类。默认情况下，事件项选择的事件将被记录。例如，以下过滤器启用了命名事件子类的记录：

{
  "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.37，“事件类和子类组合” 描述了每个事件类的允许子类值。

表 8.38，事件类和子类的日志和中止特征 描述了每个事件子类是否可以被日志或中止。

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

要执行包括日志，请禁用全局日志记录并启用特定类的日志记录。该过滤器记录 连接 和 断开连接 事件在 连接 类中，以及 通用 类中的事件：

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

要启用基于特定事件字段值的日志记录，请指定 field 项 within the log 项，指示字段名称和其预期值：

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

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

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

"::xxx" 值是符号伪常量，可以代替数字值。它们必须作为字符串引用，并且区分大小写。

在 general 类中的事件指示操作的状态代码及其详细信息。表 8.40，“一般事件字段” 指示了 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 值可以在 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.41，“表访问事件字段” 指示了 table_access 事件的允许字段。

以下列表显示哪些语句生成哪些表访问事件：

事件 项可以包括一个 abort 项，指示是否阻止合格的事件执行。abort 启用规则，以阻止特定 SQL 语句的执行。

The abort 项必须出现在 事件 项中。例如：

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

对于由 name 项选择的事件子类，abort 动作取决于 condition 评估结果。如果条件评估为 true，则事件将被阻止。否则，事件将继续执行。

The 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.38，“事件类和子类组合的日志和中止特征”）。对于不能被阻止的事件，审计日志将警告写入错误日志，而不是阻止它。

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

逻辑运算符 (and, or, not) 允许构建复杂的条件，从而实现更高级的过滤配置。以下 log 项仅记录 general 事件，其中 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 } }
              ]
            }
          ]
        }
      }
    }
  }
}

要在 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 项的允许预定义变量：

要在日志条件中引用预定义函数，请使用 function 项，指定函数名称和参数：

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

名称项应指定函数名称，不包括括号或参数列表。

参数项必须满足以下条件：

如果参数数量不正确或参数类型不正确，将发生错误。

示例：

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

前面的过滤器确定是否记录 general 类 status 事件，取决于当前用户是否在 audit_log_include_accounts 系统变量中。该用户是使用事件字段构造的。

以下列表描述了 function 项的允许预定义函数：

审核过滤器定义支持替换某些审核事件字段，以便记录的事件包含替换值，而不是原始值。这使得记录的审核记录可以包含语句摘要，而不是文字语句，这对 MySQL 部署非常有用，因为语句可能会暴露敏感值。

审核事件中的字段替换工作如下：

如表 8.45，“可替换的事件字段”所示，当前唯一可替换的字段是包含语句文本的字段（出现在 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 条目。