Skip to content

PS-9954 [DOCS] - Update Audit Log Filter examples 8.4 #522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 25, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions docs/audit-log-filter-restrictions.md
Original file line number Diff line number Diff line change
@@ -4,10 +4,17 @@

The Audit Log Filter has the following general restrictions:

* Logs only SQL statements. Statements made by NoSQL APIs, such as the Memcached API, are not logged.
The Audit Log Filter has the following general restrictions:

* Log only SQL statements. Statements made by NoSQL APIs, such as the
Memcached API, are not logged.

* Logs only the top-level statement. Statements within a stored procedure or a trigger are not logged. Does not log the file contents for statements like `LOAD_DATA`.
* Log only the top-level statement. Statements within a stored procedure
or a trigger are not logged. Do not log the file contents for statements
like `LOAD_DATA`.

* If used with a cluster, the component must be installed on each server used to execute SQL on the cluster.
* Require the component to be installed on each server used to execute SQL
on the cluster if used with a cluster.

* If used with a cluster, the application or user is responsible for aggregating all the data of each server used in the cluster.
* Hold the application or user responsible for aggregating all the data from
each server used in the cluster if used with a cluster.
115 changes: 76 additions & 39 deletions docs/audit-log-filter-variables.md
Original file line number Diff line number Diff line change
@@ -288,7 +288,7 @@ This function returns either an `OK` for success or an error message for failure

```{.bash data-prompt="mysql>"}
mysql> SET @filter = '{ "filter_name": { "log": true }}'
mysql> SET audit_log_filter_set_filter('filter-name', @filter);
mysql> SELECT audit_log_filter_set_filter('filter-name', @filter);
```

??? example "Expected output"
@@ -342,24 +342,24 @@ mysql> SELECT audit_log_filter_set_user('user-name@localhost', 'filter-name');
| Name |
| --- |
| [`audit-log-filter`](#audit-logvalue) |
| [`audit_log_filter.buffer_size`](#audit_log_filter_buffer_size) |
| [`audit_log_filter.compression`](#audit_log_filter_filter_compression) |
| [`audit_log_filter.database`](#audit_log_filter.database) |
| [`audit_log_filter.disable`](#audit_log_filter_disable) |
| [`audit_log_filter.encryption`](#audit_log_filter_encryption) |
| [`audit_log_filter.file`](#audit_log_filter_file) |
| [`audit_log_filter.format`](#audit_log_filter_format) |
| [`audit_log_filter.format_unix_timestamp`](#audit_log_filter_format_unix_timestamp) |
| [`audit_log_filter.handler`](#audit_log_filter_handler) |
| [`audit_log_filter.key_derivation_iterations_count_mean`](#audit_log_filter_key_derivation_iterations_count_mean) |
| [`audit_log_filter.max_size`](#audit_log_filter_max_size) |
| [`audit_log_filter.keep_password_history_keep_days`](#audit_log_filter_keep_password_history_keep_days) |
| [`audit_log_filter.prune_seconds`](#audit_log_filter_prune_seconds) |
| [`audit_log_filter.read_buffer_size`](#audit_log_filter_read_buffer_size) |
| [`audit_log_filter.rotate_on_size`](#audit_log_filter_rotate_on_size) |
| [`audit_log_filter.strategy`](#audit_log_filter_strategy) |
| [`audit_log_filter.syslog_tag`](#audit_log_filter_syslog_tag) |
| [`audit_log_filter.syslog_priority`](#audit_log_filter_syslog_priority) |
| [`audit_log_filter.buffer_size`](#audit_log_filterbuffer_size) |
| [`audit_log_filter.compression`](#audit_log_filtercompression) |
| [`audit_log_filter.database`](#audit_log_filterdatabase) |
| [`audit_log_filter.disable`](#audit_log_filterdisable) |
| [`audit_log_filter.encryption`](#audit_log_filterencryption) |
| [`audit_log_filter.file`](#audit_log_filterfile) |
| [`audit_log_filter.format`](#audit_log_filterformat) |
| [`audit_log_filter.format_unix_timestamp`](#audit_log_filterformat_unix_timestamp) |
| [`audit_log_filter.handler`](#audit_log_filterhandler) |
| [`audit_log_filter.key_derivation_iterations_count_mean`](#audit_log_filterkey_derivation_iterations_count_mean) |
| [`audit_log_filter.max_size`](#audit_log_filtermax_size) |
| [`audit_log_filter.password_history_keep_days`](#audit_log_filterpassword_history_keep_days) |
| [`audit_log_filter.prune_seconds`](#audit_log_filterprune_seconds) |
| [`audit_log_filter.read_buffer_size`](#audit_log_filterread_buffer_size) |
| [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size) |
| [`audit_log_filter.strategy`](#audit_log_filterstrategy) |
| [`audit_log_filter.syslog_tag`](#audit_log_filtersyslog_tag) |
| [`audit_log_filter.syslog_priority`](#audit_log_filtersyslog_priority) |

### `audit_log_filter.buffer_size`

@@ -505,7 +505,7 @@ This option does nothing when used with other format types.

Defines where the component writes the audit log filter file. The following values are available:

* `FILE` - component writes the log to a location specified in [`audit_log_filter.file`](#audit_log_filter_file)
* `FILE` - component writes the log to a location specified in [`audit_log_filter.file`](#audit_log_filterfile)
* `SYSLOG` - component writes to the syslog


@@ -547,13 +547,15 @@ A value greater than 0 (zero) enables pruning based on size and defines the comb

The value is based on 4096 (block size). A value is truncated to the nearest multiple of the block size. If the value is less than 4096, the value is treated as 0 (zero).

If the values for `audit_log_filter.rotate_on_size` and `audit_log_filter.max_size` are greater than 0, we recommend that `audit_log_filter.max_size` value should be at least seven times the `audit_log_filter.rotate_on_size` value.
If the values for [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size) and [`audit_log_filter.max_size`](#audit_log_filtermax_size) are greater than 0, we recommend that `audit_log_filter.max_size` value should be at least seven times the `audit_log_filter.rotate_on_size` value.

Pruning requires the following options:

* `audit_log_filter.max_size`
* `audit_log_filter.rotate_on_size`
* `audit_log_filter.prune_seconds`
* [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size)

* [`audit_log_filter.max_size`](#audit_log_filtermax_size)

* [`audit_log_filter.prune_seconds`](#audit_log_filterpruneseconds)


### `audit_log_filter.password_history_keep_days`
@@ -574,7 +576,7 @@ The default value is 0 (zero). This value disables the expiration of passwords.

If the component starts and encryption is enabled, the component checks for an audit log filter encryption password. If a password is not found, the component generates a random password.

Call `audit_log_filter_encryption_set()` to set a specific password.
Call [`audit_log_filter_encryption_set()`](#audit_log_filter_encryption_set) to set a specific password.


### `audit_log_filter.prune_seconds`
@@ -598,8 +600,8 @@ A value greater than 0 enables pruning. An audit log filter file can be pruned a

To enable log pruning, you must set one of the following:

* Enable log rotation by setting `audit_log_filter.rotate_on_size`
* Add a value greater than 0 (zero) for either `audit_log_filter.max_size` or `audit_log_filter.prune_seconds`
* Enable log rotation by setting [`audit_log_filter.rotate_on_size`](audit_log_filterrotate_on_size)
* Add a value greater than 0 (zero) for either [`audit_log_filter.max_size`](audit_log_filtermax_size) or [`audit_log_filter.prune_seconds`](audit_log_filterprune_seconds)


### `audit_log_filter.read_buffer_size`
@@ -615,7 +617,7 @@ To enable log pruning, you must set one of the following:

This option is only supported for JSON-format files.

The size of the buffer for reading from the audit log filter file. The `audit_log_filter_read()` reads only from this buffer size.
The size of the buffer for reading from the audit log filter file. The [`audit_log_filter_read()`](audit_log_filter_read) reads only from this buffer size.

### `audit_log_filter.rotate_on_size`

@@ -689,14 +691,49 @@ Defines the `priority` value for the syslog. The option has the same meaning as

The audit log filter component exposes status variables. These variables provide information on the operations.

| Name | Description |
| -- | --- |
| `audit_log_filter_current_size` | The current size of the audit log filter file. If the log is rotated, the size is reset to 0. |
| `audit_log_filter_direct_writes` | Identifies when the `log_strategy_type` = ASYNCHRONOUS and messages bypass the write buffer and are written directly to the log file |
| `audit_log_filter_max_drop_size` | In the performance logging mode, the size of the largest dropped event. |
| `audit_log_filter_events` | The number of audit log filter events |
| `audit_log_filter_events_filtered` | The number of filtered audit log filter component events |
| `audit_log_filter_events_lost` | If the event is larger than the available audit log filter buffer space, the event is lost |
| `audit_log_filter_events_written` | The number of audit log filter events written |
| `audit_log_filter_total_size` | The total size of the events written to all audit log filter files. The number increases even when a log is rotated |
| `audit_log_filter_write_waits` | In the asynchronous logging mode, the number of times an event waited for space in the audit log filter buffer |
<table border="0" cellpadding="6" cellspacing="0">
<thead>
<tr>
<th style="width: 40ch; white-space: nowrap;">Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>audit_log_filter_current_size</code></td>
<td>The current size of the audit log filter file. If the log is rotated, the size is reset to 0.</td>
</tr>
<tr>
<td><code>audit_log_filter_direct_writes</code></td>
<td>Identifies when the <code>log_strategy_type</code> = ASYNCHRONOUS and messages bypass the write buffer and are written directly to the log file.</td>
</tr>
<tr>
<td><code>audit_log_filter_max_drop_size</code></td>
<td>In the performance logging mode, the size of the largest dropped event.</td>
</tr>
<tr>
<td><code>audit_log_filter_events</code></td>
<td>The number of audit log filter events.</td>
</tr>
<tr>
<td><code>audit_log_filter_events_filtered</code></td>
<td>The number of filtered audit log filter component events.</td>
</tr>
<tr>
<td><code>audit_log_filter_events_lost</code></td>
<td>If the event is larger than the available audit log filter buffer space, the event is lost.</td>
</tr>
<tr>
<td><code>audit_log_filter_events_written</code></td>
<td>The number of audit log filter events written.</td>
</tr>
<tr>
<td><code>audit_log_filter_total_size</code></td>
<td>The total size of the events written to all audit log filter files. The number increases even when a log is rotated.</td>
</tr>
<tr>
<td><code>audit_log_filter_write_waits</code></td>
<td>In the asynchronous logging mode, the number of times an event waited for space in the audit log filter buffer.</td>
</tr>
</tbody>
</table>
21 changes: 10 additions & 11 deletions docs/disable-audit-log-filter.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,24 @@
# Disable Audit Log Filter logging

The `audit_log_filter.disable` system variable lets you disable or enable logging for all connections.
The `audit_log_filter.disable` system variable lets you disable or enable logging for all connections based on the value:

| Value | Actions |
|---|---|
| `audit_log_filter.disable = true` |Disables logging. |
| `audit_log_filter.disable = false` | Enables logging. |

You can set the variable in the following ways:

* Option file
* Command-line startup string
* SET statement during runtime
* Specify in the option file.

* Include in the command-line startup string.

* Use a SET statement during runtime.

```{.bash data-prompt="mysql>"}
mysql> SET GLOBAL audit_log_filter.disable = true;
```

Setting `audit_log_filter.disable` has the following effect:

| Value | Actions |
|---|---|
| true | Generates a warning. Audit log function calls and changes in variables generate session warnings. Disables the component. |
| false | Re-enables the component and generates a warning. This is the default value. |

## Privileges required

Setting the value of `audit_log_filter.disable` at runtime requires the following:
18 changes: 5 additions & 13 deletions docs/filter-audit-log-filter-files.md
Original file line number Diff line number Diff line change
@@ -152,30 +152,22 @@ Add filter_update_on_user_change.
```{.bash data-prompt="mysql>"}
mysql> SELECT audit_log_filter_set_filter('log_connect', '{
"filter": {
"class": {
"name": "connection",
"event": {
"name": "connect"
}
}
"class": { "name": "connection" },
"event": { "name": "connect" }
}
}');

mysql> SELECT audit_log_filter_set_filter('log_disconnect', '{
"filter": {
"class": {
"name": "connection",
"event": {
"name": "disconnect"
}
}
"class": { "name": "connection" },
"event": { "name": "disconnect" }
}
}');
```

| Option | Filters | Example | Event |
|-------------|---------------------------------------------|--------------------------------|-------------------------------------------|
| class | general, connection, table_access | N/A | general: Server-wide events, query processing<br>connection: Login, logout, connection attempts<br>table_access: Database and table-level interactions |
| class | general, connection, table_access | N/A | General: Server-wide events, query processing<br>connection: Login, logout, connection attempts<br>table_access: Database and table-level interactions |
| user | Filters by MySQL user accounts | ["admin", "readonly_user"] | All actions performed by specified users |
| database | Filters by database name | ["sales", "inventory"] | Operations within specified databases |
| table | Filters by table name | ["customers", "orders"] | Interactions with specific tables |
4 changes: 3 additions & 1 deletion docs/reading-audit-log-filter-files.md
Original file line number Diff line number Diff line change
@@ -9,12 +9,14 @@ If the file is renamed and no longer fits the pattern, the file is ignored.
The following functions read the files in the JSON-format:

* [`audit_log_read`](audit-log-filter-variables.md#audit_log_read) - reads audit log filter events
* [`audit_log_read_bookmark()](audit-log-filter-variables.md#audit_log_read_bookmark) - for the most recently read event, returns a bookmark. The bookmark can be passed to `audit_log_read()`.

* [`audit_log_read_bookmark`](audit-log-filter-variables.md#audit_log_read_bookmark) - for the most recently read event, returns a bookmark. This bookmark can be passed to `audit_log_read()`.

Initialize a read sequence by using a bookmark or an argument that specifies the start position:

```{.bash data-prompt="mysql>"}
mysql> SELECT audit_log_read(audit_log_read_bookmark());
```

The following example continues reading from the current position:

8 changes: 7 additions & 1 deletion docs/uninstall-audit-log-filter.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
# Uninstall Audit Log Filter

To remove the component, run the following:
If you no longer need the audit log filter functionality, you can remove the component from server using the following command:

```{.bash data-prompt="mysql>"}
mysql> UNINSTALL COMPONENT 'file://component_audit_log_filter';
```

This command does the following:

* `UNINSTALL COMPONENT`: This tells the server to remove a plugin or feature that was previously installed.

* `file://component_audit_log_filter`: This is the identifier for the Audit Log Filter Component, which is responsible for applying rules to decide which audit log events are recorded.