#### 6.4.5.11 Audit Log Reference

 The following sections provide a reference to MySQL Enterprise Audit elements:

* [Audit Log Tables](audit-log-reference.html#audit-log-tables)

* [Audit Log Functions](audit-log-reference.html#audit-log-routines)

* [Audit Log Option and Variable Reference](audit-log-reference.html#audit-log-option-variable-reference)

* [Audit Log Options and Variables](audit-log-reference.html#audit-log-options-variables)

* [Audit Log Status Variables](audit-log-reference.html#audit-log-status-variables)

 To install the audit log tables and functions, use the instructions provided in [Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Audit”](audit-log-installation.html). Unless those objects are installed, the `audit_log` plugin operates in legacy mode. See [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html).

##### Audit Log Tables

 MySQL Enterprise Audit uses tables in the `mysql` system database for persistent storage of filter and user account data. The tables can be accessed only by users who have privileges for that database. The tables use the `InnoDB` storage engine.

 If these tables are missing, the `audit_log` plugin operates in legacy mode. See [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html).

 The `audit_log_filter` table stores filter definitions. The table has these columns:

* `NAME`

   The filter name.

* `FILTER`

   The filter definition associated with the filter name. Definitions are stored as [`JSON`](json.html) values.

 The `audit_log_user` table stores user account information. The table has these columns:

* `USER`

   The user name part of an account. For an account `user1@localhost`, the `USER` part is `user1`.

* `HOST`

   The host name part of an account. For an account `user1@localhost`, the `HOST` part is `localhost`.

* `FILTERNAME`

   The name of the filter assigned to the account. The filter name associates the account with a filter defined in the `audit_log_filter` table.

##### Audit Log Functions

 This section describes, for each audit log function, its purpose, calling sequence, and return value. For information about the conditions under which these functions can be invoked, see [Section 6.4.5.7, “Audit Log Filtering”](audit-log-filtering.html).

 Each audit log function returns a string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

 As of MySQL 8.0.19, audit log functions convert string arguments to `utf8mb4` and string return values are `utf8mb4` strings. Prior to MySQL 8.0.19, audit log functions treat string arguments as binary strings (which means they do not distinguish lettercase), and string return values are binary strings.

 If an audit log function is invoked from within the [**mysql**](mysql.html) client, binary string results display using hexadecimal notation, depending on the value of the [`--binary-as-hex`](mysql-command-options.html#option_mysql_binary-as-hex). For more information about that option, see [Section 4.5.1, “mysql — The MySQL Command-Line Client”](mysql.html).

 These audit log functions are available:

* []() [`audit_log_encryption_password_get([*`keyring_id`*])`](audit-log-reference.html#function_audit-log-encryption-password-get)

  []()[]()

   This function fetches an audit log encryption password from the MySQL keyring, which must be enabled or an error occurs. Any keyring component or plugin can be used; for instructions, see [Section 6.4.4, “The MySQL Keyring”](keyring.html).

   With no argument, the function retrieves the current encryption password as a binary string. An argument may be given to specify which audit log encryption password to retrieve. The argument must be the keyring ID of the current password or an archived password.

   For additional information about audit log encryption, see [Encrypting Audit Log Files](audit-log-logging-configuration.html#audit-log-file-encryption).

   Arguments:

  *`keyring_id`*: As of MySQL 8.0.17, this optional argument indicates the keyring ID of the password to retrieve. The maximum permitted length is 766 bytes. If omitted, the function retrieves the current password.

   Prior to MySQL 8.0.17, no argument is permitted. The function always retrieves the current password.

   Return value:

   The password string for success (up to 766 bytes), or `NULL` and an error for failure.

   Example:

   Retrieve the current password:

  ```
  mysql> SELECT audit_log_encryption_password_get();
  +-------------------------------------+
  | audit_log_encryption_password_get() |
  +-------------------------------------+
  | secret                              |
  +-------------------------------------+
  ```

   To retrieve a password by ID, you can determine which audit log keyring IDs exist by querying the Performance Schema [`keyring_keys`](performance-schema-keyring-keys-table.html) table:

  []()[]()

  ```
  mysql> SELECT KEY_ID FROM performance_schema.keyring_keys
         WHERE KEY_ID LIKE 'audit_log%'
         ORDER BY KEY_ID;
  +-----------------------------+
  | KEY_ID                      |
  +-----------------------------+
  | audit_log-20190415T152248-1 |
  | audit_log-20190415T153507-1 |
  | audit_log-20190416T125122-1 |
  | audit_log-20190416T141608-1 |
  +-----------------------------+
  mysql> SELECT audit_log_encryption_password_get('audit_log-20190416T125122-1');
  +------------------------------------------------------------------+
  | audit_log_encryption_password_get('audit_log-20190416T125122-1') |
  +------------------------------------------------------------------+
  | segreto                                                          |
  +------------------------------------------------------------------+
  ```

* []() [`audit_log_encryption_password_set(*`password`*)`](audit-log-reference.html#function_audit-log-encryption-password-set)

  []()[]()

   Sets the current audit log encryption password to the argument and stores the password in the MySQL keyring. As of MySQL 8.0.19, the password is stored as a `utf8mb4` string. Prior to MySQL 8.0.19, the password is stored in binary form.

   If encryption is enabled, this function performs a log file rotation operation that renames the current log file, and begins a new log file encrypted with the password. The keyring must be enabled or an error occurs. Any keyring component or plugin can be used; for instructions, see [Section 6.4.4, “The MySQL Keyring”](keyring.html).

   For additional information about audit log encryption, see [Encrypting Audit Log Files](audit-log-logging-configuration.html#audit-log-file-encryption).

   Arguments:

  *`password`*: The password string. The maximum permitted length is 766 bytes.

   Return value:

   1 for success, 0 for failure.

   Example:

  ```
  mysql> SELECT audit_log_encryption_password_set(password);
  +---------------------------------------------+
  | audit_log_encryption_password_set(password) |
  +---------------------------------------------+
  | 1                                           |
  +---------------------------------------------+
  ```

* []() [`audit_log_filter_flush()`](audit-log-reference.html#function_audit-log-filter-flush)

  []()[]()

   Calling any of the other filtering functions affects operational audit log filtering immediately and updates the audit log tables. If instead you modify the contents of those tables directly using statements such as [`INSERT`](insert.html), [`UPDATE`](update.html), and [`DELETE`](delete.html), the changes do not affect filtering immediately. To flush your changes and make them operational, call [`audit_log_filter_flush()`](audit-log-reference.html#function_audit-log-filter-flush).

  Warning

  [`audit_log_filter_flush()`](audit-log-reference.html#function_audit-log-filter-flush) should be used only after modifying the audit tables directly, to force reloading all filters. Otherwise, this function should be avoided. It is, in effect, a simplified version of unloading and reloading the `audit_log` plugin with [`UNINSTALL PLUGIN`](uninstall-plugin.html) plus [`INSTALL PLUGIN`](install-plugin.html).

  [`audit_log_filter_flush()`](audit-log-reference.html#function_audit-log-filter-flush) affects all current sessions and detaches them from their previous filters. Current sessions are no longer logged unless they disconnect and reconnect, or execute a change-user operation.

   If this function fails, an error message is returned and the audit log is disabled until the next successful call to [`audit_log_filter_flush()`](audit-log-reference.html#function_audit-log-filter-flush).

   Arguments:

   None.

   Return value:

   A string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

   Example:

  ```
  mysql> SELECT audit_log_filter_flush();
  +--------------------------+
  | audit_log_filter_flush() |
  +--------------------------+
  | OK                       |
  +--------------------------+
  ```

* []() [`audit_log_filter_remove_filter(*`filter_name`*)`](audit-log-reference.html#function_audit-log-filter-remove-filter)

  []()[]()

   Given a filter name, removes the filter from the current set of filters. It is not an error for the filter not to exist.

   If a removed filter is assigned to any user accounts, those users stop being filtered (they are removed from the `audit_log_user` table). Termination of filtering includes any current sessions for those users: They are detached from the filter and no longer logged.

   Arguments:

  * *`filter_name`*: A string that specifies the filter name.

   Return value:

   A string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

   Example:

  ```
  mysql> SELECT audit_log_filter_remove_filter('SomeFilter');
  +----------------------------------------------+
  | audit_log_filter_remove_filter('SomeFilter') |
  +----------------------------------------------+
  | OK                                           |
  +----------------------------------------------+
  ```

* []() [`audit_log_filter_remove_user(*`user_name`*)`](audit-log-reference.html#function_audit-log-filter-remove-user)

  []()[]()

   Given a user account name, cause the user to be no longer assigned to a filter. It is not an error if the user has no filter assigned. Filtering of current sessions for the user remains unaffected. New connections for the user are filtered using the default account filter if there is one, and are not logged otherwise.

   If the name is `%`, the function removes the default account filter that is used for any user account that has no explicitly assigned filter.

   Arguments:

  * *`user_name`*: The user account name as a string in `*`user_name`*@*`host_name`*` format, or `%` to represent the default account.

   Return value:

   A string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

   Example:

  ```
  mysql> SELECT audit_log_filter_remove_user('user1@localhost');
  +-------------------------------------------------+
  | audit_log_filter_remove_user('user1@localhost') |
  +-------------------------------------------------+
  | OK                                              |
  +-------------------------------------------------+
  ```

* []() [`audit_log_filter_set_filter(*`filter_name`*, *`definition`*)`](audit-log-reference.html#function_audit-log-filter-set-filter)

  []()[]()

   Given a filter name and definition, adds the filter to the current set of filters. If the filter already exists and is used by any current sessions, those sessions are detached from the filter and are no longer logged. This occurs because the new filter definition has a new filter ID that differs from its previous ID.

   Arguments:

  * *`filter_name`*: A string that specifies the filter name.

  * *`definition`*: A [`JSON`](json.html) value that specifies the filter definition.

   Return value:

   A string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

   Example:

  ```
  mysql> SET @f = '{ "filter": { "log": false } }';
  mysql> SELECT audit_log_filter_set_filter('SomeFilter', @f);
  +-----------------------------------------------+
  | audit_log_filter_set_filter('SomeFilter', @f) |
  +-----------------------------------------------+
  | OK                                            |
  +-----------------------------------------------+
  ```

* []() [`audit_log_filter_set_user(*`user_name`*, *`filter_name`*)`](audit-log-reference.html#function_audit-log-filter-set-user)

  []()[]()

   Given a user account name and a filter name, assigns the filter to the user. A user can be assigned only one filter, so if the user was already assigned a filter, the assignment is replaced. Filtering of current sessions for the user remains unaffected. New connections are filtered using the new filter.

   As a special case, the name `%` represents the default account. The filter is used for connections from any user account that has no explicitly assigned filter.

   Arguments:

  * *`user_name`*: The user account name as a string in `*`user_name`*@*`host_name`*` format, or `%` to represent the default account.

  * *`filter_name`*: A string that specifies the filter name.

   Return value:

   A string that indicates whether the operation succeeded. `OK` indicates success. `ERROR: *`message`*` indicates failure.

   Example:

  ```
  mysql> SELECT audit_log_filter_set_user('user1@localhost', 'SomeFilter');
  +------------------------------------------------------------+
  | audit_log_filter_set_user('user1@localhost', 'SomeFilter') |
  +------------------------------------------------------------+
  | OK                                                         |
  +------------------------------------------------------------+
  ```

* []() [`audit_log_read([*`arg`*])`](audit-log-reference.html#function_audit-log-read)

  []()[]()

   Reads the audit log and returns a [`JSON`](json.html) string result. If the audit log format is not [`JSON`](json.html), an error occurs.

   With no argument or a [`JSON`](json.html) hash argument, [`audit_log_read()`](audit-log-reference.html#function_audit-log-read) reads events from the audit log and returns a [`JSON`](json.html) string containing an array of audit events. Items in the hash argument influence how reading occurs, as described later. Each element in the returned array is an event represented as a [`JSON`](json.html) hash, with the exception that the last element may be a [`JSON`](json.html) `null` value to indicate no following events are available to read.

   With an argument consisting of a [`JSON`](json.html) `null` value, [`audit_log_read()`](audit-log-reference.html#function_audit-log-read) closes the current read sequence.

   For additional details about the audit log-reading process, see [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

   Arguments:

   To obtain a bookmark for the most recently written event, call [`audit_log_read_bookmark()`](audit-log-reference.html#function_audit-log-read-bookmark).

  *`arg`*: The argument is optional. If omitted, the function reads events from the current position. If present, the argument can be a [`JSON`](json.html) `null` value to close the read sequence, or a [`JSON`](json.html) hash. Within a hash argument, items are optional and control aspects of the read operation such as the position at which to begin reading or how many events to read. The following items are significant (other items are ignored):

  * `start`: The position within the audit log of the first event to read. The position is given as a timestamp and the read starts from the first event that occurs on or after the timestamp value. The `start` item has this format, where *`value`* is a literal timestamp value:

    ```
    "start": { "timestamp": "value" }
    ```

     The `start` item is permitted as of MySQL 8.0.22.

  * `timestamp`, `id`: The position within the audit log of the first event to read. The `timestamp` and `id` items together comprise a bookmark that uniquely identify a particular event. If an [`audit_log_read()`](audit-log-reference.html#function_audit-log-read) argument includes either item, it must include both to completely specify a position or an error occurs.

  * `max_array_length`: The maximum number of events to read from the log. If this item is omitted, the default is to read to the end of the log or until the read buffer is full, whichever comes first.

   To specify a starting position to [`audit_log_read()`](audit-log-reference.html#function_audit-log-read), pass a hash argument that includes either a `start` item or a bookmark consisting of `timestamp` and `id` items. If a hash argument includes both a `start` item and a bookmark, an error occurs.

   If a hash argument specifies no starting position, reading continues from the current position.

   If a timestamp value includes no time part, a time part of `00:00:00` is assumed.

   Return value:

   If the call succeeds, the return value is a [`JSON`](json.html) string containing an array of audit events, or a [`JSON`](json.html) `null` value if that was passed as the argument to close the read sequence. If the call fails, the return value is `NULL` and an error occurs.

   Example:

  ```
  mysql> SELECT audit_log_read(audit_log_read_bookmark());
  +-----------------------------------------------------------------------+
  | audit_log_read(audit_log_read_bookmark())                             |
  +-----------------------------------------------------------------------+
  | [ {"timestamp":"2020-05-18 22:41:24","id":0,"class":"connection", ... |
  +-----------------------------------------------------------------------+
  mysql> SELECT audit_log_read('null');
  +------------------------+
  | audit_log_read('null') |
  +------------------------+
  | null                   |
  +------------------------+
  ```

   Notes:

   Prior to MySQL 8.0.19, string return values are binary [`JSON`](json.html) strings. For information about converting such values to nonbinary strings, see [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

* []() [`audit_log_read_bookmark()`](audit-log-reference.html#function_audit-log-read-bookmark)

  []()[]()

   Returns a [`JSON`](json.html) string representing a bookmark for the most recently written audit log event. If the audit log format is not [`JSON`](json.html), an error occurs.

   The bookmark is a [`JSON`](json.html) hash with `timestamp` and `id` items that uniquely identify the position of an event within the audit log. It is suitable for passing to [`audit_log_read()`](audit-log-reference.html#function_audit-log-read) to indicate to that function the position at which to begin reading.

   For additional details about the audit log-reading process, see [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

   Arguments:

   None.

   Return value:

   A [`JSON`](json.html) string containing a bookmark for success, or `NULL` and an error for failure.

   Example:

  ```
  mysql> SELECT audit_log_read_bookmark();
  +-------------------------------------------------+
  | audit_log_read_bookmark()                       |
  +-------------------------------------------------+
  | { "timestamp": "2019-10-03 21:03:44", "id": 0 } |
  +-------------------------------------------------+
  ```

   Notes:

   Prior to MySQL 8.0.19, string return values are binary [`JSON`](json.html) strings. For information about converting such values to nonbinary strings, see [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

##### Audit Log Option and Variable Reference

[]()

**Table 6.43 Audit Log Option and Variable Reference**

|                                                      Name                                                       |Cmd-Line|Option File|System Var|Status Var|Var Scope|Dynamic|
|-----------------------------------------------------------------------------------------------------------------|--------|-----------|----------|----------|---------|-------|
|                          [audit-log](audit-log-reference.html#option_mysqld_audit-log)                          |  Yes   |    Yes    |          |          |         |       |
|                [audit\_log\_buffer\_size](audit-log-reference.html#sysvar_audit_log_buffer_size)                |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|                [audit\_log\_compression](audit-log-reference.html#sysvar_audit_log_compression)                 |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|          [audit\_log\_connection\_policy](audit-log-reference.html#sysvar_audit_log_connection_policy)          |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|            [audit\_log\_current\_session](audit-log-reference.html#sysvar_audit_log_current_session)            |        |           |   Yes    |          |  Both   |  No   |
|              [Audit\_log\_current\_size](audit-log-reference.html#statvar_Audit_log_current_size)               |        |           |          |   Yes    | Global  |  No   |
|                    [audit\_log\_disable](audit-log-reference.html#sysvar_audit_log_disable)                     |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|                 [audit\_log\_encryption](audit-log-reference.html#sysvar_audit_log_encryption)                  |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|      [Audit\_log\_event\_max\_drop\_size](audit-log-reference.html#statvar_Audit_log_event_max_drop_size)       |        |           |          |   Yes    | Global  |  No   |
|                     [Audit\_log\_events](audit-log-reference.html#statvar_Audit_log_events)                     |        |           |          |   Yes    | Global  |  No   |
|           [Audit\_log\_events\_filtered](audit-log-reference.html#statvar_Audit_log_events_filtered)            |        |           |          |   Yes    | Global  |  No   |
|               [Audit\_log\_events\_lost](audit-log-reference.html#statvar_Audit_log_events_lost)                |        |           |          |   Yes    | Global  |  No   |
|            [Audit\_log\_events\_written](audit-log-reference.html#statvar_Audit_log_events_written)             |        |           |          |   Yes    | Global  |  No   |
|           [audit\_log\_exclude\_accounts](audit-log-reference.html#sysvar_audit_log_exclude_accounts)           |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|                       [audit\_log\_file](audit-log-reference.html#sysvar_audit_log_file)                        |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|                  [audit\_log\_filter\_id](audit-log-reference.html#sysvar_audit_log_filter_id)                  |        |           |   Yes    |          |  Both   |  No   |
|                      [audit\_log\_flush](audit-log-reference.html#sysvar_audit_log_flush)                       |        |           |   Yes    |          | Global  |  Yes  |
|                     [audit\_log\_format](audit-log-reference.html#sysvar_audit_log_format)                      |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|           [audit\_log\_include\_accounts](audit-log-reference.html#sysvar_audit_log_include_accounts)           |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|[audit\_log\_password\_history\_keep\_days](audit-log-reference.html#sysvar_audit_log_password_history_keep_days)|  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|                     [audit\_log\_policy](audit-log-reference.html#sysvar_audit_log_policy)                      |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|              [audit\_log\_prune\_seconds](audit-log-reference.html#sysvar_audit_log_prune_seconds)              |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|          [audit\_log\_read\_buffer\_size](audit-log-reference.html#sysvar_audit_log_read_buffer_size)           |  Yes   |    Yes    |   Yes    |          | Varies  |Varies |
|            [audit\_log\_rotate\_on\_size](audit-log-reference.html#sysvar_audit_log_rotate_on_size)             |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|           [audit\_log\_statement\_policy](audit-log-reference.html#sysvar_audit_log_statement_policy)           |  Yes   |    Yes    |   Yes    |          | Global  |  Yes  |
|                   [audit\_log\_strategy](audit-log-reference.html#sysvar_audit_log_strategy)                    |  Yes   |    Yes    |   Yes    |          | Global  |  No   |
|                [Audit\_log\_total\_size](audit-log-reference.html#statvar_Audit_log_total_size)                 |        |           |          |   Yes    | Global  |  No   |
|               [Audit\_log\_write\_waits](audit-log-reference.html#statvar_Audit_log_write_waits)                |        |           |          |   Yes    | Global  |  No   |

##### Audit Log Options and Variables

 This section describes the command options and system variables that configure operation of MySQL Enterprise Audit. If values specified at startup time are incorrect, the `audit_log` plugin may fail to initialize properly and the server does not load it. In this case, the server may also produce error messages for other audit log settings because it does not recognize them.

 To configure activation of the audit log plugin, use this option:

* []() [`--audit-log[=*`value`*]`](audit-log-reference.html#option_mysqld_audit-log)

  []()[]()

  |Command-Line Format|                       `--audit-log[=value]`                        |
  |-------------------|--------------------------------------------------------------------|
  |       Type        |                            Enumeration                             |
  |   Default Value   |                                `ON`                                |
  |   Valid Values    |`ON`<br/><br/>`OFF`<br/><br/>`FORCE`<br/><br/>`FORCE_PLUS_PERMANENT`|

   This option controls how the server loads the `audit_log` plugin at startup. It is available only if the plugin has been previously registered with [`INSTALL PLUGIN`](install-plugin.html) or is loaded with [`--plugin-load`](server-options.html#option_mysqld_plugin-load) or [`--plugin-load-add`](server-options.html#option_mysqld_plugin-load-add). See [Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Audit”](audit-log-installation.html).

   The option value should be one of those available for plugin-loading options, as described in [Section 5.6.1, “Installing and Uninstalling Plugins”](plugin-loading.html). For example, [`--audit-log=FORCE_PLUS_PERMANENT`](audit-log-reference.html#option_mysqld_audit-log) tells the server to load the plugin and prevent it from being removed while the server is running.

 If the audit log plugin is enabled, it exposes several system variables that permit control over logging:

```
mysql> SHOW VARIABLES LIKE 'audit_log%';
+-----------------------------+--------------+
| Variable_name               | Value        |
+-----------------------------+--------------+
| audit_log_buffer_size       | 1048576      |
| audit_log_connection_policy | ALL          |
| audit_log_current_session   | OFF          |
| audit_log_exclude_accounts  |              |
| audit_log_file              | audit.log    |
| audit_log_filter_id         | 0            |
| audit_log_flush             | OFF          |
| audit_log_format            | NEW          |
| audit_log_include_accounts  |              |
| audit_log_policy            | ALL          |
| audit_log_rotate_on_size    | 0            |
| audit_log_statement_policy  | ALL          |
| audit_log_strategy          | ASYNCHRONOUS |
+-----------------------------+--------------+
```

 You can set any of these variables at server startup, and some of them at runtime. Those that are available only for legacy mode audit log filtering are so noted.

* []() [`audit_log_buffer_size`](audit-log-reference.html#sysvar_audit_log_buffer_size)

  []()[]()

  |                         Command-Line Format                          |                          `--audit-log-buffer-size=#`                           |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_buffer_size](audit-log-reference.html#sysvar_audit_log_buffer_size)`|
  |                                Scope                                 |                                     Global                                     |
  |                               Dynamic                                |                                       No                                       |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                       No                                       |
  |                                 Type                                 |                                    Integer                                     |
  |                            Default Value                             |                                   `1048576`                                    |
  |                            Minimum Value                             |                                     `4096`                                     |
  |                   Maximum Value (64-bit platforms)                   |                             `18446744073709547520`                             |
  |                   Maximum Value (32-bit platforms)                   |                                  `4294967295`                                  |
  |                              Block Size                              |                                     `4096`                                     |

   When the audit log plugin writes events to the log asynchronously, it uses a buffer to store event contents prior to writing them. This variable controls the size of that buffer, in bytes. The server adjusts the value to a multiple of 4096. The plugin uses a single buffer, which it allocates when it initializes and removes when it terminates. The plugin allocates this buffer only if logging is asynchronous.

* []() [`audit_log_disable`](audit-log-reference.html#sysvar_audit_log_disable)

  []()[]()

  |                         Command-Line Format                          |                    `--audit-log-disable[={OFF|ON}]`                    |
  |----------------------------------------------------------------------|------------------------------------------------------------------------|
  |                              Introduced                              |                                 8.0.28                                 |
  |                           System Variable                            |`[audit_log_disable](audit-log-reference.html#sysvar_audit_log_disable)`|
  |                                Scope                                 |                                 Global                                 |
  |                               Dynamic                                |                                  Yes                                   |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                   No                                   |
  |                                 Type                                 |                                Boolean                                 |
  |                            Default Value                             |                                 `OFF`                                  |

   Permits disabling audit logging for all connecting and connected sessions. In addition to the [`SYSTEM_VARIABLES_ADMIN`](privileges-provided.html#priv_system-variables-admin) privilege, disabling audit logging requires the [`AUDIT_ADMIN`](privileges-provided.html#priv_audit-admin) privilege. See [Section 6.4.5.9, “Disabling Audit Logging”](audit-log-disabling.html).

* []() [`audit_log_compression`](audit-log-reference.html#sysvar_audit_log_compression)

  []()[]()

  |                         Command-Line Format                          |                        `--audit-log-compression=value`                         |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_compression](audit-log-reference.html#sysvar_audit_log_compression)`|
  |                                Scope                                 |                                     Global                                     |
  |                               Dynamic                                |                                       No                                       |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                       No                                       |
  |                                 Type                                 |                                  Enumeration                                   |
  |                            Default Value                             |                                     `NONE`                                     |
  |                             Valid Values                             |                             `NONE`<br/><br/>`GZIP`                             |

   The type of compression for the audit log file. Permitted values are `NONE` (no compression; the default) and `GZIP` (GNU Zip compression). For more information, see [Compressing Audit Log Files](audit-log-logging-configuration.html#audit-log-file-compression).

* []() [`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-connection-policy=value`                            |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_connection_policy](audit-log-reference.html#sysvar_audit_log_connection_policy)`|
  |                                Scope                                 |                                           Global                                           |
  |                               Dynamic                                |                                            Yes                                             |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                             No                                             |
  |                                 Type                                 |                                        Enumeration                                         |
  |                            Default Value                             |                                           `ALL`                                            |
  |                             Valid Values                             |                          `ALL`<br/><br/>`ERRORS`<br/><br/>`NONE`                           |

  Note

   This variable applies only to legacy mode audit log filtering (see [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html)).

   The policy controlling how the audit log plugin writes connection events to its log file. The following table shows the permitted values.

  | Value  |           Description           |
  |--------|---------------------------------|
  | `ALL`  |    Log all connection events    |
  |`ERRORS`|Log only failed connection events|
  | `NONE` |  Do not log connection events   |

  Note

   At server startup, any explicit value given for [`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy) may be overridden if [`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy) is also specified, as described in [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`audit_log_current_session`](audit-log-reference.html#sysvar_audit_log_current_session)

  []()[]()

  |                           System Variable                            |`[audit_log_current_session](audit-log-reference.html#sysvar_audit_log_current_session)`|
  |----------------------------------------------------------------------|----------------------------------------------------------------------------------------|
  |                                Scope                                 |                                    Global, Session                                     |
  |                               Dynamic                                |                                           No                                           |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                           No                                           |
  |                                 Type                                 |                                        Boolean                                         |
  |                            Default Value                             |                             `depends on filtering policy`                              |

   Whether audit logging is enabled for the current session. The session value of this variable is read only. It is set when the session begins based on the values of the [`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts) and [`audit_log_exclude_accounts`](audit-log-reference.html#sysvar_audit_log_exclude_accounts) system variables. The audit log plugin uses the session value to determine whether to audit events for the session. (There is a global value, but the plugin does not use it.)

* []() [`audit_log_encryption`](audit-log-reference.html#sysvar_audit_log_encryption)

  []()[]()

  |                         Command-Line Format                          |                        `--audit-log-encryption=value`                        |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_encryption](audit-log-reference.html#sysvar_audit_log_encryption)`|
  |                                Scope                                 |                                    Global                                    |
  |                               Dynamic                                |                                      No                                      |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                      No                                      |
  |                                 Type                                 |                                 Enumeration                                  |
  |                            Default Value                             |                                    `NONE`                                    |
  |                             Valid Values                             |                            `NONE`<br/><br/>`AES`                             |

   The type of encryption for the audit log file. Permitted values are `NONE` (no encryption; the default) and `AES` (AES-256-CBC cipher encryption). For more information, see [Encrypting Audit Log Files](audit-log-logging-configuration.html#audit-log-file-encryption).

* []() [`audit_log_exclude_accounts`](audit-log-reference.html#sysvar_audit_log_exclude_accounts)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-exclude-accounts=value`                           |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_exclude_accounts](audit-log-reference.html#sysvar_audit_log_exclude_accounts)`|
  |                                Scope                                 |                                          Global                                          |
  |                               Dynamic                                |                                           Yes                                            |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                            No                                            |
  |                                 Type                                 |                                          String                                          |
  |                            Default Value                             |                                          `NULL`                                          |

  Note

   This variable applies only to legacy mode audit log filtering (see [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html)).

   The accounts for which events should not be logged. The value should be `NULL` or a string containing a list of one or more comma-separated account names. For more information, see [Section 6.4.5.7, “Audit Log Filtering”](audit-log-filtering.html).

   Modifications to [`audit_log_exclude_accounts`](audit-log-reference.html#sysvar_audit_log_exclude_accounts) affect only connections created subsequent to the modification, not existing connections.

* []() [`audit_log_file`](audit-log-reference.html#sysvar_audit_log_file)

  []()[]()

  |                         Command-Line Format                          |                   `--audit-log-file=file_name`                   |
  |----------------------------------------------------------------------|------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_file](audit-log-reference.html#sysvar_audit_log_file)`|
  |                                Scope                                 |                              Global                              |
  |                               Dynamic                                |                                No                                |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                No                                |
  |                                 Type                                 |                            File name                             |
  |                            Default Value                             |                           `audit.log`                            |

   The base name and suffix of the file to which the audit log plugin writes events. The default value is `audit.log`, regardless of logging format. To have the name suffix correspond to the format, set the name explicitly, choosing a different suffix (for example, `audit.xml` for XML format, `audit.json` for JSON format).

   If the value of [`audit_log_file`](audit-log-reference.html#sysvar_audit_log_file) is a relative path name, the plugin interprets it relative to the data directory. If the value is a full path name, the plugin uses the value as is. A full path name may be useful if it is desirable to locate audit files on a separate file system or directory. For security reasons, write the audit log file to a directory accessible only to the MySQL server and to users with a legitimate reason to view the log.

   For details about how the audit log plugin interprets the [`audit_log_file`](audit-log-reference.html#sysvar_audit_log_file) value and the rules for file renaming that occurs at plugin initialization and termination, see [Naming Conventions for Audit Log Files](audit-log-logging-configuration.html#audit-log-file-name).

   The audit log plugin uses the directory containing the audit log file (determined from the [`audit_log_file`](audit-log-reference.html#sysvar_audit_log_file) value) as the location to search for readable audit log files. From these log files and the current file, the plugin constructs a list of the ones that are subject to use with the audit log bookmarking and reading functions. See [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

* []() [`audit_log_filter_id`](audit-log-reference.html#sysvar_audit_log_filter_id)

  []()[]()

  |                           System Variable                            |`[audit_log_filter_id](audit-log-reference.html#sysvar_audit_log_filter_id)`|
  |----------------------------------------------------------------------|----------------------------------------------------------------------------|
  |                                Scope                                 |                              Global, Session                               |
  |                               Dynamic                                |                                     No                                     |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                     No                                     |
  |                                 Type                                 |                                  Integer                                   |

   The session value of this variable indicates the internally maintained ID of the audit filter for the current session. A value of 0 means that the session has no filter assigned.

* []() [`audit_log_flush`](audit-log-reference.html#sysvar_audit_log_flush)

  []()[]()

  |                           System Variable                            |`[audit_log_flush](audit-log-reference.html#sysvar_audit_log_flush)`|
  |----------------------------------------------------------------------|--------------------------------------------------------------------|
  |                                Scope                                 |                               Global                               |
  |                               Dynamic                                |                                Yes                                 |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                 No                                 |
  |                                 Type                                 |                              Boolean                               |
  |                            Default Value                             |                               `OFF`                                |

   If [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) is 0, automatic audit log file rotation is disabled and rotation occurs only when performed manually. In that case, enabling [`audit_log_flush`](audit-log-reference.html#sysvar_audit_log_flush) by setting it to 1 or `ON` causes the audit log plugin to close and reopen its log file to flush it. (The variable value remains `OFF` so that you need not disable it explicitly before enabling it again to perform another flush.) For more information, see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`audit_log_format`](audit-log-reference.html#sysvar_audit_log_format)

  []()[]()

  |                         Command-Line Format                          |                      `--audit-log-format=value`                      |
  |----------------------------------------------------------------------|----------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_format](audit-log-reference.html#sysvar_audit_log_format)`|
  |                                Scope                                 |                                Global                                |
  |                               Dynamic                                |                                  No                                  |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                  No                                  |
  |                                 Type                                 |                             Enumeration                              |
  |                            Default Value                             |                                `NEW`                                 |
  |                             Valid Values                             |                 `OLD`<br/><br/>`NEW`<br/><br/>`JSON`                 |

   The audit log file format. Permitted values are `OLD` (old-style XML), `NEW` (new-style XML; the default), and `JSON`. For details about each format, see [Section 6.4.5.4, “Audit Log File Formats”](audit-log-file-formats.html).

  Note

   For information about issues to consider when changing the log format, see [Selecting Audit Log File Format](audit-log-logging-configuration.html#audit-log-file-format).

* []() [`audit_log_format_unix_timestamp`](audit-log-reference.html#sysvar_audit_log_format_unix_timestamp)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-format-unix-timestamp[={OFF|ON}]`                           |
  |----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
  |                              Introduced                              |                                               8.0.26                                               |
  |                           System Variable                            |`[audit_log_format_unix_timestamp](audit-log-reference.html#sysvar_audit_log_format_unix_timestamp)`|
  |                                Scope                                 |                                               Global                                               |
  |                               Dynamic                                |                                                Yes                                                 |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                                 No                                                 |
  |                                 Type                                 |                                              Boolean                                               |
  |                            Default Value                             |                                               `OFF`                                                |

   This variable applies only for JSON-format audit log output. When that is true, enabling this variable causes each log file record to include a `time` field. The field value is an integer that represents the UNIX timestamp value indicating the date and time when the audit event was generated.

   Changing the value of this variable at runtime causes log file rotation so that, for a given JSON-format log file, all records in the file either do or do not include the `time` field.

   Setting the runtime value of [`audit_log_format_unix_timestamp`](audit-log-reference.html#sysvar_audit_log_format_unix_timestamp) requires the [`AUDIT_ADMIN`](privileges-provided.html#priv_audit-admin) privilege, in addition to the [`SYSTEM_VARIABLES_ADMIN`](privileges-provided.html#priv_system-variables-admin) privilege (or the deprecated [`SUPER`](privileges-provided.html#priv_super) privilege) normally required to set a global system variable runtime value.

* []() [`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-include-accounts=value`                           |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_include_accounts](audit-log-reference.html#sysvar_audit_log_include_accounts)`|
  |                                Scope                                 |                                          Global                                          |
  |                               Dynamic                                |                                           Yes                                            |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                            No                                            |
  |                                 Type                                 |                                          String                                          |
  |                            Default Value                             |                                          `NULL`                                          |

  Note

   This variable applies only to legacy mode audit log filtering (see [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html)).

   The accounts for which events should be logged. The value should be `NULL` or a string containing a list of one or more comma-separated account names. For more information, see [Section 6.4.5.7, “Audit Log Filtering”](audit-log-filtering.html).

   Modifications to [`audit_log_include_accounts`](audit-log-reference.html#sysvar_audit_log_include_accounts) affect only connections created subsequent to the modification, not existing connections.

* []() [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size)

  []()[]()

  |                         Command-Line Format                          |                         `--audit-log-max-size=#`                         |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------|
  |                              Introduced                              |                                  8.0.26                                  |
  |                           System Variable                            |`[audit_log_max_size](audit-log-reference.html#sysvar_audit_log_max_size)`|
  |                                Scope                                 |                                  Global                                  |
  |                               Dynamic                                |                                   Yes                                    |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                    No                                    |
  |                                 Type                                 |                                 Integer                                  |
  |                            Default Value                             |                                   `0`                                    |
  |                            Minimum Value                             |                                   `0`                                    |
  |                       Maximum Value (Windows)                        |                               `4294967295`                               |
  |                        Maximum Value (Other)                         |                          `18446744073709551615`                          |
  |                                 Unit                                 |                                 `bytes`                                  |
  |                              Block Size                              |                                  `4096`                                  |

  [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) pertains to audit log file pruning, which is supported for JSON-format log files only. It controls pruning based on combined log file size:

  * A value of 0 (the default) disables size-based pruning. No size limit is enforced.

  * A value greater than 0 enables size-based pruning. The value is the combined size above which audit log files become subject to pruning.

   If you set [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) to a value that is not a multiple of 4096, it is truncated to the nearest multiple. In particular, setting it to a value less than 4096 sets it to 0 and no size-based pruning occurs.

   If both [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) and [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) are greater than 0, [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) should be more than 7 times the value of [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size). Otherwise, a warning is written to the server error log because in this case the “granularity” of size-based pruning may be insufficient to prevent removal of all or most rotated log files each time it occurs.

  Note

   Setting [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) by itself is not sufficient to cause log file pruning to occur because the pruning algorithm uses [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size), [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size), and [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds) in conjunction. For details, see [Space Management of Audit Log Files](audit-log-logging-configuration.html#audit-log-space-management).

* []() [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days)

  []()[]()

  |                         Command-Line Format                          |                                  `--audit-log-password-history-keep-days=#`                                  |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
  |                              Introduced                              |                                                    8.0.17                                                    |
  |                           System Variable                            |`[audit_log_password_history_keep_days](audit-log-reference.html#sysvar_audit_log_password_history_keep_days)`|
  |                                Scope                                 |                                                    Global                                                    |
  |                               Dynamic                                |                                                     Yes                                                      |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                                      No                                                      |
  |                                 Type                                 |                                                   Integer                                                    |
  |                            Default Value                             |                                                     `0`                                                      |
  |                            Minimum Value                             |                                                     `0`                                                      |
  |                            Maximum Value                             |                                                 `4294967295`                                                 |

   The audit log plugin implements log file encryption using encryption passwords stored in the MySQL keyring (see [Encrypting Audit Log Files](audit-log-logging-configuration.html#audit-log-file-encryption)). The plugin also implements password history, which includes password archiving and expiration (removal).

   When the audit log plugin creates a new encryption password, it archives the previous password, if one exists, for later use. The [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days) variable controls automatic removal of expired archived passwords. Its value indicates the number of days after which archived audit log encryption passwords are removed. The default of 0 disables password expiration: the password retention period is forever.

   New audit log encryption passwords are created under these circumstances:

  * During plugin initialization, if the plugin finds that log file encryption is enabled, it checks whether the keyring contains an audit log encryption password. If not, the plugin automatically generates a random initial encryption password.

  * When the [`audit_log_encryption_password_set()`](audit-log-reference.html#function_audit-log-encryption-password-set) function is called to set a specific password.

   In each case, the plugin stores the new password in the key ring and uses it to encrypt new log files.

   Removal of expired audit log encryption passwords occurs under these circumstances:

  * During plugin initialization.

  * When the [`audit_log_encryption_password_set()`](audit-log-reference.html#function_audit-log-encryption-password-set) function is called.

  * When the runtime value of [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days) is changed from its current value to a value greater than 0. Runtime value changes occur for [`SET`](set-variable.html) statements that use the `GLOBAL` or `PERSIST` keyword, but not the `PERSIST_ONLY` keyword. `PERSIST_ONLY` writes the variable setting to `mysqld-auto.cnf`, but has no effect on the runtime value.

    []()[]()

   When password removal occurs, the current value of [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days) determines which passwords to remove:

  * If the value is 0, the plugin removes no passwords.

  * If the value is *`N`* \> 0, the plugin removes passwords more than *`N`* days old.

  Note

   Take care not to expire old passwords that are still needed to read archived encrypted log files.

   If you normally leave password expiration disabled (that is, [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days) has a value of 0), it is possible to perform an on-demand cleanup operation by temporarily assigning the variable a value greater than zero. For example, to expire passwords older than 365 days, do this:

  ```
  SET GLOBAL audit_log_password_history_keep_days = 365;
  SET GLOBAL audit_log_password_history_keep_days = 0;
  ```

   Setting the runtime value of [`audit_log_password_history_keep_days`](audit-log-reference.html#sysvar_audit_log_password_history_keep_days) requires the [`AUDIT_ADMIN`](privileges-provided.html#priv_audit-admin) privilege, in addition to the [`SYSTEM_VARIABLES_ADMIN`](privileges-provided.html#priv_system-variables-admin) privilege (or the deprecated [`SUPER`](privileges-provided.html#priv_super) privilege) normally required to set a global system variable runtime value.

* []() [`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy)

  []()[]()

  |                         Command-Line Format                          |                      `--audit-log-policy=value`                      |
  |----------------------------------------------------------------------|----------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_policy](audit-log-reference.html#sysvar_audit_log_policy)`|
  |                                Scope                                 |                                Global                                |
  |                               Dynamic                                |                                  No                                  |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                  No                                  |
  |                                 Type                                 |                             Enumeration                              |
  |                            Default Value                             |                                `ALL`                                 |
  |                             Valid Values                             |      `ALL`<br/><br/>`LOGINS`<br/><br/>`QUERIES`<br/><br/>`NONE`      |

  Note

   This variable applies only to legacy mode audit log filtering (see [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html)).

   The policy controlling how the audit log plugin writes events to its log file. The following table shows the permitted values.

  |  Value  |             Description              |
  |---------|--------------------------------------|
  |  `ALL`  |            Log all events            |
  |`LOGINS` |        Log only login events         |
  |`QUERIES`|        Log only query events         |
  | `NONE`  |Log nothing (disable the audit stream)|

  [`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy) can be set only at server startup. At runtime, it is a read-only variable. Two other system variables, [`audit_log_connection_policy`](audit-log-reference.html#sysvar_audit_log_connection_policy) and [`audit_log_statement_policy`](audit-log-reference.html#sysvar_audit_log_statement_policy), provide finer control over logging policy and can be set either at startup or at runtime. If you use [`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy) at startup instead of the other two variables, the server uses its value to set those variables. For more information about the policy variables and their interaction, see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-prune-seconds=#`                            |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------------|
  |                              Introduced                              |                                       8.0.24                                       |
  |                           System Variable                            |`[audit_log_prune_seconds](audit-log-reference.html#sysvar_audit_log_prune_seconds)`|
  |                                Scope                                 |                                       Global                                       |
  |                               Dynamic                                |                                        Yes                                         |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                         No                                         |
  |                                 Type                                 |                                      Integer                                       |
  |                            Default Value                             |                                        `0`                                         |
  |                            Minimum Value                             |                                        `0`                                         |
  |                       Maximum Value (Windows)                        |                                    `4294967295`                                    |
  |                        Maximum Value (Other)                         |                               `18446744073709551615`                               |
  |                                 Unit                                 |                                      `bytes`                                       |

  [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds) pertains to audit log file pruning, which is supported for JSON-format log files only. It controls pruning based on log file age:

  * A value of 0 (the default) disables age-based pruning. No age limit is enforced.

  * A value greater than 0 enables age-based pruning. The value is the number of seconds after which audit log files become subject to pruning.

  Note

   Setting [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds) by itself is not sufficient to cause log file pruning to occur because the pruning algorithm uses [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size), [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size), and [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds) in conjunction. For details, see [Space Management of Audit Log Files](audit-log-logging-configuration.html#audit-log-space-management).

* []() [`audit_log_read_buffer_size`](audit-log-reference.html#sysvar_audit_log_read_buffer_size)

  []()[]()

  |                         Command-Line Format                          |                             `--audit-log-read-buffer-size=#`                             |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_read_buffer_size](audit-log-reference.html#sysvar_audit_log_read_buffer_size)`|
  |                           Scope (≥ 8.0.12)                           |                                     Global, Session                                      |
  |                            Scope (8.0.11)                            |                                          Global                                          |
  |                          Dynamic (≥ 8.0.12)                          |                                           Yes                                            |
  |                           Dynamic (8.0.11)                           |                                            No                                            |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                            No                                            |
  |                                 Type                                 |                                         Integer                                          |
  |                       Default Value (≥ 8.0.12)                       |                                         `32768`                                          |
  |                        Default Value (8.0.11)                        |                                        `1048576`                                         |
  |                       Minimum Value (≥ 8.0.12)                       |                                         `32768`                                          |
  |                        Minimum Value (8.0.11)                        |                                          `1024`                                          |
  |                            Maximum Value                             |                                        `4194304`                                         |

   The buffer size for reading from the audit log file, in bytes. The [`audit_log_read()`](audit-log-reference.html#function_audit-log-read) function reads no more than this many bytes. Log file reading is supported only for JSON log format. For more information, see [Section 6.4.5.6, “Reading Audit Log Files”](audit-log-file-reading.html).

   As of MySQL 8.0.12, this variable has a default of 32KB and can be set at runtime. Each client should set its session value of [`audit_log_read_buffer_size`](audit-log-reference.html#sysvar_audit_log_read_buffer_size) appropriately for its use of [`audit_log_read()`](audit-log-reference.html#function_audit-log-read). Prior to MySQL 8.0.12, [`audit_log_read_buffer_size`](audit-log-reference.html#sysvar_audit_log_read_buffer_size) has a default of 1MB, affects all clients, and can be changed only at server startup.

* []() [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size)

  []()[]()

  |                         Command-Line Format                          |                            `--audit-log-rotate-on-size=#`                            |
  |----------------------------------------------------------------------|--------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_rotate_on_size](audit-log-reference.html#sysvar_audit_log_rotate_on_size)`|
  |                                Scope                                 |                                        Global                                        |
  |                               Dynamic                                |                                         Yes                                          |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                          No                                          |
  |                                 Type                                 |                                       Integer                                        |
  |                            Default Value                             |                                         `0`                                          |
  |                            Minimum Value                             |                                         `0`                                          |
  |                            Maximum Value                             |                                `18446744073709551615`                                |
  |                                 Unit                                 |                                       `bytes`                                        |
  |                              Block Size                              |                                        `4096`                                        |

   If [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) is 0, the audit log plugin does not perform automatic size-based log file rotation. If rotation is to occur, you must perform it manually; see [Manual Audit Log File Rotation](audit-log-logging-configuration.html#audit-log-manual-rotation).

   If [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) is greater than 0, automatic size-based log file rotation occurs. Whenever a write to the log file causes its size to exceed the [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) value, the audit log plugin renames the current log file and opens a new current log file using the original name.

   If you set [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) to a value that is not a multiple of 4096, it is truncated to the nearest multiple. In particular, setting it to a value less than 4096 sets it to 0 and no rotation occurs, except manually.

  Note

  [`audit_log_rotate_on_size`](audit-log-reference.html#sysvar_audit_log_rotate_on_size) controls whether audit log file rotation occurs. It can also be used in conjunction with [`audit_log_max_size`](audit-log-reference.html#sysvar_audit_log_max_size) and [`audit_log_prune_seconds`](audit-log-reference.html#sysvar_audit_log_prune_seconds) to configure pruning of rotated JSON-format log files. For details, see [Space Management of Audit Log Files](audit-log-logging-configuration.html#audit-log-space-management).

* []() [`audit_log_statement_policy`](audit-log-reference.html#sysvar_audit_log_statement_policy)

  []()[]()

  |                         Command-Line Format                          |                           `--audit-log-statement-policy=value`                           |
  |----------------------------------------------------------------------|------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[audit_log_statement_policy](audit-log-reference.html#sysvar_audit_log_statement_policy)`|
  |                                Scope                                 |                                          Global                                          |
  |                               Dynamic                                |                                           Yes                                            |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                            No                                            |
  |                                 Type                                 |                                       Enumeration                                        |
  |                            Default Value                             |                                          `ALL`                                           |
  |                             Valid Values                             |                         `ALL`<br/><br/>`ERRORS`<br/><br/>`NONE`                          |

  Note

   This variable applies only to legacy mode audit log filtering (see [Section 6.4.5.10, “Legacy Mode Audit Log Filtering”](audit-log-legacy-filtering.html)).

   The policy controlling how the audit log plugin writes statement events to its log file. The following table shows the permitted values.

  | Value  |          Description           |
  |--------|--------------------------------|
  | `ALL`  |    Log all statement events    |
  |`ERRORS`|Log only failed statement events|
  | `NONE` |  Do not log statement events   |

  Note

   At server startup, any explicit value given for [`audit_log_statement_policy`](audit-log-reference.html#sysvar_audit_log_statement_policy) may be overridden if [`audit_log_policy`](audit-log-reference.html#sysvar_audit_log_policy) is also specified, as described in [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`audit_log_strategy`](audit-log-reference.html#sysvar_audit_log_strategy)

  []()[]()

  |                         Command-Line Format                          |                             `--audit-log-strategy=value`                              |
  |----------------------------------------------------------------------|---------------------------------------------------------------------------------------|
  |                           System Variable                            |      `[audit_log_strategy](audit-log-reference.html#sysvar_audit_log_strategy)`       |
  |                                Scope                                 |                                        Global                                         |
  |                               Dynamic                                |                                          No                                           |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                          No                                           |
  |                                 Type                                 |                                      Enumeration                                      |
  |                            Default Value                             |                                    `ASYNCHRONOUS`                                     |
  |                             Valid Values                             |`ASYNCHRONOUS`<br/><br/>`PERFORMANCE`<br/><br/>`SEMISYNCHRONOUS`<br/><br/>`SYNCHRONOUS`|

   The logging method used by the audit log plugin. These strategy values are permitted:

  * `ASYNCHRONOUS`: Log asynchronously. Wait for space in the output buffer.

  * `PERFORMANCE`: Log asynchronously. Drop requests for which there is insufficient space in the output buffer.

  * `SEMISYNCHRONOUS`: Log synchronously. Permit caching by the operating system.

  * `SYNCHRONOUS`: Log synchronously. Call `sync()` after each request.

##### Audit Log Status Variables

 If the audit log plugin is enabled, it exposes several status variables that provide operational information. These variables are available for legacy mode audit filtering and JSON mode audit filtering.

* []() [`Audit_log_current_size`](audit-log-reference.html#statvar_Audit_log_current_size)

  []()[]()

   The size of the current audit log file. The value increases when an event is written to the log and is reset to 0 when the log is rotated.

* []() [`Audit_log_event_max_drop_size`](audit-log-reference.html#statvar_Audit_log_event_max_drop_size)

  []()[]()

   The size of the largest dropped event in performance logging mode. For a description of logging modes, see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`Audit_log_events`](audit-log-reference.html#statvar_Audit_log_events)

  []()[]()

   The number of events handled by the audit log plugin, whether or not they were written to the log based on filtering policy (see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html)).

* []() [`Audit_log_events_filtered`](audit-log-reference.html#statvar_Audit_log_events_filtered)

  []()[]()

   The number of events handled by the audit log plugin that were filtered (not written to the log) based on filtering policy (see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html)).

* []() [`Audit_log_events_lost`](audit-log-reference.html#statvar_Audit_log_events_lost)

  []()[]()

   The number of events lost in performance logging mode because an event was larger than the available audit log buffer space. This value may be useful for assessing how to set [`audit_log_buffer_size`](audit-log-reference.html#sysvar_audit_log_buffer_size) to size the buffer for performance mode. For a description of logging modes, see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

* []() [`Audit_log_events_written`](audit-log-reference.html#statvar_Audit_log_events_written)

  []()[]()

   The number of events written to the audit log.

* []() [`Audit_log_total_size`](audit-log-reference.html#statvar_Audit_log_total_size)

  []()[]()

   The total size of events written to all audit log files. Unlike [`Audit_log_current_size`](audit-log-reference.html#statvar_Audit_log_current_size), the value of [`Audit_log_total_size`](audit-log-reference.html#statvar_Audit_log_total_size) increases even when the log is rotated.

* []() [`Audit_log_write_waits`](audit-log-reference.html#statvar_Audit_log_write_waits)

  []()[]()

   The number of times an event had to wait for space in the audit log buffer in asynchronous logging mode. For a description of logging modes, see [Section 6.4.5.5, “Configuring Audit Logging Characteristics”](audit-log-logging-configuration.html).

