Merge pull request #581 from percona/ps-10217-8.4

PS-10217 [DOCS] - Audit log filter installation cannot be done with I…

Author: patrickbirch

docs/install-audit-log-filter.md

@@ -1,24 +1,129 @@
-# Install the Audit Log Filter
+# Install the audit log filter
 
-The `plugin_dir` system variable defines the component library location. If needed, at server startup, set the `plugin_dir` variable.
+## Installation script
 
-In the `share` directory, locate the `audit_log_filter_linux_install.sql ` script.
+The recommended way to install the component is to use the `audit_log_filter_linux_install.sql` script, located in the `share` directory, which creates the required tables before installing the component.
 
-At the time you run the script, you can select the database used to store the JSON filter tables.
+### Prerequisites
 
-* If the component is loaded, the installation script takes the database name from the `audit_log_filter.database` variable
-* If the component is not loaded, but passes the `-D db_name` to the mysql client when the installation script runs, uses the `db_name`.
-* If the component is not loaded and the `-D` option is not provided, the installation script creates the required tables in the default database name `mysql`.
+The `plugin_dir` system variable defines the component library location. If needed, set the `plugin_dir` variable at server startup.
+
+### Database selection
+
+The script determines the target database using the following priority:
+
+* If the component is already loaded, the script uses the database name from the `audit_log_filter.database` variable
+
+* If the component is not loaded, but you pass the `-D db_name` option to the mysql client when running the script, it uses the specified `db_name`
+
+* If the component is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script
 
 You can also designate a different database with the `audit_log_filter.database` system variable. The database name cannot be NULL or exceed 64 characters. If the database name is invalid, the audit log filter tables are not found.
 
-To install the component, run the following command:
+### Install the component
+
+To install the component using the script, you must specify the `mysql` database. You can do this in two ways:
+
+* Option 1: Run the script from the command line with the `-D mysql` option:
+
+    ```{.bash data-prompt="$"}
+    mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
+    ```
+
+* Option 2: Connect to `mysql` database and run the script interactively:
+
+    ```{.bash data-prompt="mysql>"}
+    mysql> use mysql;
+    mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
+    ```
+
+    Replace `/path/to/mysql/share/` with the actual path to your MySQL installation's share directory.
+
+### Verify installation
+
+After running the script, verify that the required tables are created:
+
+```{.bash data-prompt="mysql>"}
+mysql> show tables in mysql like 'aud%';
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +------------------------+
+    | Tables_in_mysql (aud%) |
+    +------------------------+
+    | audit_log_filter       |
+    | audit_log_user         |
+    +------------------------+
+    2 rows in set (0.00 sec)
+    ```
+
+## Alternative: INSTALL COMPONENT method
+
+You can also install the component using the `INSTALL COMPONENT` command, but this method does not create the required tables and will cause filter operations to fail.
+
+### Verify component installation
+
+Check that the component is properly installed:
 
 ```{.bash data-prompt="mysql>"}
-mysql> INSTALL COMPONENT 'file://component_audit_log_filter';
+mysql> select * from mysql.component;
 ```
 
-Find more information in the [INSTALL COMPONENT](install-component.md) document.
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +--------------+--------------------+------------------------------------+
+    | component_id | component_group_id | component_urn                      |
+    +--------------+--------------------+------------------------------------+
+    |            1 |                  1 | file://component_percona_telemetry |
+    |            2 |                  2 | file://component_audit_log_filter  |
+    +--------------+--------------------+------------------------------------+
+    2 rows in set (0.00 sec)
+    ```
+
+### Test filter functionality
+
+Test that the audit log filter is working correctly:
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}');
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +---------------------------------------------------------------------+
+    | audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}') |
+    +---------------------------------------------------------------------+
+    | ERROR: Failed to check filtering rule name existence                |
+    +---------------------------------------------------------------------+
+    1 row in set (0.00 sec)
+    ```
+
+!!! note
+
+    This error occurs when the component is installed without the required tables. Using the SQL script prevents this issue.
+
+### Fix missing tables
+
+If you have already installed the audit log component but are missing the required tables, you can run the `audit_log_filter_linux_install.sql` script to create the audit tables in the `mysql` database:
+
+```{.bash data-prompt="$"}
+mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
+```
+
+Or interactively:
+
+```{.bash data-prompt="mysql>"}
+mysql> use mysql;
+mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
+```
+
+This operation creates the missing tables without reinstalling the component.
+
+## Additional information
 
 To upgrade from `audit_log_filter` plugin in Percona Server 8.4 to `component_audit_log_filter` component in Percona Server {{vers}}, do the [manual upgrade](upgrade-components.md).