Merge pull request #584 from percona/ps-10226-8.4

PS-10226 - [DOCS] Audit log changes in documentation 8.4

Author: patrickbirch

docs/audit-log-filter-new.md

@@ -4,7 +4,7 @@ The filter writes the audit log filter file in XML. The XML file uses
 UTF-8.
 
 The <AUDIT> is the root element and this element contains 
-<AUDIT_RECORD> elements. Each <AUDIT_RECORD> element contains specific 
+&lt;AUDIT_RECORD&gt; elements. Each &lt;AUDIT_RECORD&gt; element contains specific 
 information about an event that is audited. 
 
 For each new file, the Audit Log Filter component writes the XML 
@@ -76,7 +76,7 @@ closing element is not available.
 </AUDIT>
 ```
 
-The order of the attributes within an <AUDIT_RECORD> can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record.
+The order of the attributes within an &lt;AUDIT_RECORD&gt; can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record.
 
 The attributes in every element are the following:
 

docs/audit-log-filter-old.md

@@ -1,8 +1,8 @@
 # Audit Log Filter format - XML (old style)
 
-The old style XML format uses `<AUDIT>` tag as the root element and adds the `</AUDIT>` tag when the file closes. Each audited event is contained in an <AUDIT_RECORD> element. 
+The old style XML format uses `<AUDIT>` tag as the root element and adds the `</AUDIT>` tag when the file closes. Each audited event is contained in an &lt;AUDIT_RECORD&gt; element. 
 
-The order of the attributes within an <AUDIT_RECORD> can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record.
+The order of the attributes within an &lt;AUDIT_RECORD&gt; can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record.
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>

docs/write-filter-definitions.md

@@ -350,24 +350,31 @@ Performance impact is a critical consideration when implementing detailed loggin
 
 ## Implement the filter
 
-Here's how to define and implement an audit log filter:
+Here's how to define and implement an audit log filter in Percona Server for MySQL 8.4.6:
 
-### Add filter identifier
+### Create a filter
 
-An audit log filter identifier is your filter's unique name within the `audit_log_filter` system. You create this name to label and track your specific filter setup. The `audit_log_filter_id` system variable stores this name, and you should choose descriptive identifiers like 'finance_audit' or 'security_tracking'.
+To create an audit log filter, use the `audit_log_filter_set_filter()` function. This function takes two parameters: the filter name and the filter definition as a JSON string.
 
-After you name your filter with an identifier, you attach your rules. The identifier makes it easy to manage multiple filter setups and update them as needed. When you want to change your logging rules, you first reference your chosen identifier and then add your new filter settings.
+```sql
+SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }');
+```
+
+### Assign filter to users
 
-Remember that when you apply new filter settings to an existing identifier, the system replaces the old settings. It doesn't add the new rules to what's already there.
+To assign a filter to specific users, use the `audit_log_filter_set_user()` function. This function takes three parameters: username, userhost, and filtername.
 
 ```sql
-SET GLOBAL audit_log_filter_id = 'financial_tracking';
+SELECT audit_log_filter_set_user('%', '%', 'log_all');
 ```
 
-### Add filter definition
+### Example: Financial tracking filter
+
+Here's a complete example of creating and assigning a comprehensive financial tracking filter:
 
 ```sql
-SET GLOBAL audit_log_filter = '{
+-- Create the filter
+SELECT audit_log_filter_set_filter('financial_tracking', '{
   "filter": {
     "class": [
       {
@@ -379,7 +386,7 @@ SET GLOBAL audit_log_filter = '{
           {"name":"insert"},
           {"name":"update"},
           {"name":"delete"],
-        ]
+        ],
         "status": [0, 1]
       },
       {
@@ -393,7 +400,10 @@ SET GLOBAL audit_log_filter = '{
       }
     ]
   }
-}';
+}');
+
+-- Assign the filter to all users
+SELECT audit_log_filter_set_user('%', '%', 'financial_tracking');
 ```
 
 The filter monitors two main types of activities. First, it watches all changes to your accounts and transactions tables. This monitoring means that the filter logs when someone adds new data, changes existing information, or removes records. You get a complete picture of who's touching your financial data and what they do with it.
@@ -413,9 +423,14 @@ The filter focuses only on activity in your `financial_db` database. This target
 Tracking all these elements gives you a comprehensive view of who's accessing your financial data, what changes they're making, and whether those changes are successful. This ability is beneficial for security monitoring and compliance requirements.
 
 
-To verify your filter:
+To verify your filter, you can check the audit tables:
+
 ```sql
-SHOW GLOBAL VARIABLES LIKE 'audit_log_filter';
+-- Check created filters
+SELECT * FROM mysql.audit_log_filter;
+
+-- Check user assignments
+SELECT * FROM mysql.audit_log_user;
 ```
 
 You can examine your audit log file (the default location is the data directory) to check if events are being logged.