PS-10161 [DOCS] - pre_authenticate and general log events are still generated even when user filter is set to {"filter": {"log": false}}

	new file:   docs/write-audit-log-filter-definitions.md
	modified:   mkdocs-base.yml

Author: patrickbirch

docs/write-audit-log-filter-definitions.md

@@ -0,0 +1,236 @@
+# Write Audit‑Log Filter definitions
+
+Percona Server's audit‑log-filter plugin lets you control which events are recorded by supplying a JSON filter definition.
+
+A filter is stored in the `mysql.audit_log_filter` table and then attached to one or more MySQL accounts through the mysql.`audit_log_user` table.
+
+The following is a step‑by‑step guide that shows how to create a filter, attach it to a user, and verify that the desired events are captured or suppressed.
+
+## Filter JSON structure
+
+A filter consists of a top‑level object named `filter`.
+
+Inside this object you can set a global `log` flag and optionally define an array called `class`.
+
+Each element of the `class` array identifies a class name (for example, `connection`, `general`, `query`, `table_access`). 
+
+Each class element may contain an `event` object that specifies particular events and whether they should be logged.
+
+```json
+{
+  "filter": {
+    "log": true,
+    "class": [
+      {
+        "name": "connection",
+        "event": {
+          "name": "connect",
+          "log": true
+        }
+      },
+      {
+        "name": "query",
+        "event": {
+          "name": "execute",
+          "log": true
+        }
+      }
+    ]
+  }
+}
+```
+If the `log` flag is omitted, the default value is `true`.
+When `log` is set to `false`, the filter disables logging for all statement‑type events unless a class entry overrides that setting.
+
+## Practical example
+
+Suppose you want a user named `excludeUserTest` to generate no audit records for statements, but the server should keep a generic record that a connection was established.
+
+First create a filter that disables logging globally:
+
+```{.bash data-prompt="mysql>"}
+mysql> INSERT INTO mysql.audit_log_filter (filter_id, name, filter) VALUES
+(1, 'log_none',
+ '{"filter": {"log": false}}');
+```
+
+Ensure `filter_id` is unique; attempting to reuse an existing ID raises a duplicate-key error.
+
+Next map the filter to the user:
+
+```{.bash data-prompt="mysql>"}
+mysql> INSERT INTO mysql.audit_log_user (username, userhost, filtername) VALUES
+('excludeUserTest', '%', 'log_none');
+```
+
+After the insertion, reload the audit log filter plugin so the new configuration becomes active:
+
+```{.bash data-prompt="mysql>"}
+mysql> CALL mysql.audit_log_reload(); 
+``` 
+
+When `excludeUserTest` connects and runs queries, the audit log contains only the generic connection record that the plugin writes automatically.
+
+### Limitation – connection‑related events logged
+
+Even when a filter contains only `{"filter": {"log": false}}`, two kinds of audit records continue to appear:
+
+| Event                   | Class      | When generated                                                                 |
+|-------------------------|------------|--------------------------------------------------------------------------------|
+| `pre_authenticate`         | `connection` | Before the server identifies the user. The default mapping (`% → log_all`) applies. |
+| `general / log` (status 0) | `general`    | At session start. The filter does not disable the `general` class, so a record is written. |
+
+To prevent these records, create a filter that explicitly disables the `connection` and `general` classes and assign it to the user:
+
+```{.bash data-prompt="mysql>"}
+mysql> INSERT INTO mysql.audit_log_filter (filter_id, name, filter) VALUES
+(2, 'log_none_strict',
+ '{
+    "filter": {
+      "log": false,
+      "class": [
+        {"name": "connection", "event": {"name": "pre_authenticate", "log": false}},
+        {"name": "general",     "event": {"name": "log",            "log": false}}
+      ]
+    }
+  }');
+
+
+mysql> UPDATE mysql.audit_log_user
+   SET filtername = 'log_none_strict'
+ WHERE username = 'excludeUserTest' AND userhost = '%';
+
+mysql> CALL mysql.audit_log_reload();
+```
+
+After the reload, connections made by `excludeUserTest` will no longer generate the `pre_authenticate` or `general / log entries`.
+
+## View existing filters and mappings
+
+You can list the filters that are currently defined.
+
+```{.bash data-prompt="mysql>"}
+SELECT filter_id, name, filter FROM mysql.audit_log_filter;
+```
+
+You can also list the user‑to‑filter mappings.
+
+```{.bash data-prompt="mysql>"}
+SELECT username, userhost, filtername FROM mysql.audit_log_user;
+```
+
+These queries help you verify that the intended filter is attached to the correct accounts.
+
+## Verify the filter
+
+1. Rotate or remove the current audit log filter file so you can see fresh output.
+
+2. Connect to the server as `excludeUserTest` and run a simple query, for example, `SELECT 1;`.
+
+3. Examine the audit log filter file (default location `/var/lib/mysql/audit.log`) with `tail -f /var/lib/mysql/audit.log`.
+
+4. Confirm that only the events you intended to keep appear.
+
+If unexpected events are still present, double‑check the JSON syntax, ensure the filter ID is unique, and verify that the reload statement succeeded without errors.
+
+## Common errors and solutions
+
+### JSON syntax errors
+
+Error: `ERROR 3130 (22032): Invalid JSON text in argument 1 to function audit_log_filter_set_filter`
+
+Solution: Validate your JSON syntax before inserting. Common issues include:
+- Missing commas between array elements
+- Unmatched quotes or braces
+- Trailing commas
+
+Use a JSON validator or test with a simple filter first:
+```{.bash data-prompt="mysql>"}
+mysql> SELECT JSON_VALID('{"filter": {"log": false}}');
+```
+
+### Duplicate key errors
+
+Error: `ERROR 1062 (23000): Duplicate entry '1' for key 'PRIMARY'`
+
+Solution: Use a unique `filter_id` or check existing filters:
+```{.bash data-prompt="mysql>"}
+mysql> SELECT MAX(filter_id) FROM mysql.audit_log_filter;
+```
+
+### Plugin reload failures
+
+Error: `ERROR 1305 (42000): FUNCTION mysql.audit_log_reload does not exist`
+
+Solution: Ensure the audit log plugin is installed and active:
+```{.bash data-prompt="mysql>"}
+mysql> SHOW PLUGINS WHERE Name = 'audit_log';
+mysql> INSTALL PLUGIN audit_log SONAME 'audit_log.so';
+```
+
+### Filter not taking effect
+
+Symptoms: Expected events still appear in audit log
+
+Solutions:
+
+1. Verify the filter is properly assigned to the user:
+   ```{.bash data-prompt="mysql>"}
+   mysql> SELECT * FROM mysql.audit_log_user WHERE username = 'your_user';
+   ```
+
+2. Check for conflicting filters or default mappings:
+   ```{.bash data-prompt="mysql>"}
+   mysql> SELECT * FROM mysql.audit_log_user WHERE userhost = '%';
+   ```
+
+3. Ensure the plugin reload completed successfully:
+   ```{.bash data-prompt="mysql>"}
+   mysql> CALL mysql.audit_log_reload();
+   ```
+
+## Troubleshoot and checklist
+
+* Define the JSON filter with the desired global `log` flag.
+
+* Add class entries for any event type that must be treated differently from the global setting.
+
+* Insert the filter into `mysql.audit_log_filter` with a unique `filter_id`.
+
+* Map the filter to the appropriate MySQL accounts in `mysql.audit_log_user`.
+
+* Reload the audit plugin to apply the changes.
+
+* Test the configuration with a fresh connection and inspect the audit log.
+
+This checklist ensures that the audit log filter records exactly the events you need while omitting unnecessary noise.
+
+## Resources
+
+### Related Audit Log Filter Topics
+
+* [Audit Log Filter overview](audit-log-filter-overview.md) - Learn about the plugin's capabilities and architecture
+
+* [Install the Audit Log Filter](install-audit-log-filter.md) - Installation instructions and prerequisites
+
+* [Audit log filter functions, options and variables](audit-log-filter-variables.md) - Complete reference for configuration options
+
+* [Filter the Audit Log Filter logs](filter-audit-log-filter-files.md) - Advanced filtering using function calls
+
+* [Audit Log Filter file format overview](audit-log-filter-formats.md) - Understanding log file formats (JSON, XML)
+
+* [Audit Log Filter security](audit-log-filter-security.md) - Security considerations and best practices
+
+* [Audit Log Filter restrictions](audit-log-filter-restrictions.md) - Known limitations and constraints
+
+* [Manage the Audit Log Filter files](manage-audit-log-filter.md) - File management and rotation
+
+### Troubleshooting and Support
+
+* [Frequently asked questions](faq.md) - Common questions and answers
+
+* [Get help from Percona](get-help.md) - Community support and expert services
+
+* [Glossary](glossary.md) - Technical terms and definitions
+
+* [Percona Monitoring and Management](https://docs.percona.com/percona-monitoring-and-management) - Monitoring and performance analysis

mkdocs-base.yml

@@ -224,6 +224,7 @@ nav:
             - XML (New style): audit-log-filter-new.md
             - XML (Old style): audit-log-filter-old.md
             - JSON: audit-log-filter-json.md
+          - write-audit-log-filter-definitions.md
           - audit-log-filter-security.md
           - audit-log-filter-compression-encryption.md
           - reading-audit-log-filter-files.md