6.5.4.6 Audit Log Reference

The following discussion serves as a reference to MySQL Enterprise Audit components:

• Section 6.5.4.6.1, “Audit Log Option and Variable Reference”

• Section 6.5.4.6.2, “Audit Log Options and System Variables”

• Section 6.5.4.6.3, “Audit Log Plugin Status Variables”

6.5.4.6.1 Audit Log Option and Variable Reference

Table 6.17 Audit Log Option/Variable Reference

Name	Cmd-Line	Option File	System Var	Status Var	Var Scope	Dynamic
audit-log	Yes	Yes
audit_log_buffer_size	Yes	Yes	Yes		Global	No
audit_log_connection_policy	Yes	Yes	Yes		Global	Yes
audit_log_current_session			Yes		Both	No
Audit_log_current_size				Yes	Global	No
Audit_log_event_max_drop_size				Yes	Global	No
Audit_log_events				Yes	Global	No
Audit_log_events_filtered				Yes	Global	No
Audit_log_events_lost				Yes	Global	No
Audit_log_events_written				Yes	Global	No
audit_log_exclude_accounts	Yes	Yes	Yes		Global	Yes
audit_log_file	Yes	Yes	Yes		Global	No
audit_log_flush			Yes		Global	Yes
audit_log_format	Yes	Yes	Yes		Global	No
audit_log_include_accounts	Yes	Yes	Yes		Global	Yes
audit_log_policy	Yes	Yes	Yes		Global	Varies
audit_log_rotate_on_size	Yes	Yes	Yes		Global	Yes
audit_log_statement_policy	Yes	Yes	Yes		Global	Yes
audit_log_strategy	Yes	Yes	Yes		Global	No
Audit_log_total_size				Yes	Global	No
Audit_log_write_waits				Yes	Global	No

6.5.4.6.2 Audit Log Options and System Variables

This section describes the command options and system variables that control 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 will not recognize them.

To control the activation of the audit_log plugin, use this option:

• --audit-log[=value]

  Introduced	5.6.10
  Command-Line Format	--audit-log[=value]
  Permitted Values	Type	enumeration
  	Default	ON
  	Valid Values	ON
  		OFF
  		FORCE
  		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 or is loaded with --plugin-load or --plugin-load-add. See Section 6.5.4.1, “Installing MySQL Enterprise Audit”.

  The option value should be one of those available for plugin-loading options, as described in Section 5.5.2, “Installing and Uninstalling Plugins”. For example, --audit-log=FORCE_PLUS_PERMANENT tells the server to load the plugin at startup and prevents 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   | ON           |
| audit_log_exclude_accounts  |              |
| audit_log_file              | audit.log    |
| audit_log_flush             | OFF          |
| audit_log_format            | OLD          |
| 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.

• audit_log_buffer_size

  Introduced	5.6.10
  Command-Line Format	--audit-log-buffer-size=value
  System Variable	Name	audit_log_buffer_size
  	Variable Scope	Global
  	Dynamic Variable	No
  Permitted Values (32-bit platforms)	Type	integer
  	Default	1048576
  	Min Value	4096
  	Max Value	4294967295
  Permitted Values (64-bit platforms)	Type	integer
  	Default	1048576
  	Min Value	4096
  	Max Value	18446744073709547520

  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_connection_policy

  Introduced	5.6.20
  Command-Line Format	--audit-log-connection-policy=value
  System Variable	Name	audit_log_connection_policy
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	enumeration
  	Default	ALL
  	Valid Values	ALL
  		ERRORS
  		NONE

  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 may be overridden if audit_log_policy is also specified, as described in Section 6.5.4.4, “Audit Log Logging Control”.

• audit_log_current_session

  Introduced	5.6.20
  System Variable	Name	audit_log_current_session
  	Variable Scope	Global, Session
  	Dynamic Variable	No
  Permitted Values	Type	boolean
  	Default	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 and 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_exclude_accounts

  Introduced	5.6.20
  Command-Line Format	--audit-log-exclude-accounts=value
  System Variable	Name	audit_log_exclude_accounts
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	string
  	Default	NULL

  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.5.4.4, “Audit Log Logging Control”.

  Modifications to audit_log_exclude_accounts affect only connections created subsequent to the modification, not existing connections.

• audit_log_file

  Introduced	5.6.10
  Command-Line Format	--audit-log-file=file_name
  System Variable	Name	audit_log_file
  	Variable Scope	Global
  	Dynamic Variable	No
  Permitted Values	Type	file name
  	Default	audit.log

  The name of the file to which the audit log plugin writes events. The default value is audit.log. If the value of audit_log_file is a relative path name, the server interprets it relative to the data directory. If the value is a full path name, the server 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, the audit log file should be written to a directory accessible only to the MySQL server and users with a legitimate reason to view the log. For more information, see Section 6.5.4.4, “Audit Log Logging Control”.

• audit_log_flush

  Introduced	5.6.10
  System Variable	Name	audit_log_flush
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	boolean
  	Default	OFF

  When this variable is set to enabled (1 or ON), the audit log plugin closes and reopens its log file to flush it. (The value remains OFF so that you need not disable it explicitly before enabling it again to perform another flush.) Enabling this variable has no effect unless audit_log_rotate_on_size is 0. For more information, see Section 6.5.4.4, “Audit Log Logging Control”.

• audit_log_format

  Introduced	5.6.14
  Command-Line Format	--audit-log-format=value
  System Variable	Name	audit_log_format
  	Variable Scope	Global
  	Dynamic Variable	No
  Permitted Values (>= 5.6.14)	Type	enumeration
  	Default	OLD
  	Valid Values	OLD
  		NEW

  The audit log file format. Permitted values are OLD and NEW (default OLD). For details about each format, see Section 6.5.4.3, “The Audit Log File”.

  If you change the value of audit_log_format, use this procedure to avoid writing log entries in one format to an existing log file that contains entries in a different format:

  1. Stop the server.

  2. Rename the current audit log file manually.

  3. Restart the server with the new value of audit_log_format. The audit log plugin will create a new log file, which will contain log entries in the selected format.

• audit_log_include_accounts

  Introduced	5.6.20
  Command-Line Format	--audit-log-include-accounts=value
  System Variable	Name	audit_log_include_accounts
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	string
  	Default	NULL

  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.5.4.4, “Audit Log Logging Control”.

  Modifications to audit_log_include_accounts affect only connections created subsequent to the modification, not existing connections.

• audit_log_policy

  Introduced	5.6.10
  Command-Line Format	--audit-log-policy=value
  System Variable (<= 5.6.19)	Name	audit_log_policy
  	Variable Scope	Global
  	Dynamic Variable	Yes
  System Variable (>= 5.6.20)	Name	audit_log_policy
  	Variable Scope	Global
  	Dynamic Variable	No
  Permitted Values	Type	enumeration
  	Default	ALL
  	Valid Values	ALL
  		LOGINS
  		QUERIES
  		NONE

  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)

  As of MySQL 5.6.20, audit_log_policy can be set only at server startup. At runtime, it is a read-only variable. This is due to the introduction of two other system variables, audit_log_connection_policy and audit_log_statement_policy, that provide finer control over logging policy and that can be set either at startup or at runtime. If you continue to use 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.5.4.4, “Audit Log Logging Control”.

  Before MySQL 5.6.20, the audit_log_connection_policy and audit_log_statement_policy system variables do not exist. audit_log_policy is the only policy control variable and it can be set at server startup or runtime.

• audit_log_rotate_on_size

  Introduced	5.6.10
  Command-Line Format	--audit-log-rotate-on-size=N
  System Variable	Name	audit_log_rotate_on_size
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	integer
  	Default	0

  If the audit_log_rotate_on_size value is greater than 0, the audit log plugin closes and reopens its log file if a write to the file causes its size to exceed this value. The original file is renamed to have a timestamp extension.

  If the audit_log_rotate_on_size value is 0, the plugin does not close and reopen its log based on size. Instead, use audit_log_flush to close and reopen the log on demand. In this case, rename the file externally to the server before flushing it.

  For more information about audit log file rotation and timestamp interpretation, see Section 6.5.4.4, “Audit Log Logging Control”.

  If you set this variable to a value that is not a multiple of 4096, it is truncated to the nearest multiple. (Thus, setting it to a value less than 4096 has the effect of setting it to 0 and no rotation occurs.)

• audit_log_statement_policy

  Introduced	5.6.20
  Command-Line Format	--audit-log-statement-policy=value
  System Variable	Name	audit_log_statement_policy
  	Variable Scope	Global
  	Dynamic Variable	Yes
  Permitted Values	Type	enumeration
  	Default	ALL
  	Valid Values	ALL
  		ERRORS
  		NONE

  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 may be overridden if audit_log_policy is also specified, as described in Section 6.5.4.4, “Audit Log Logging Control”.

• audit_log_strategy

  Introduced	5.6.10
  Command-Line Format	--audit-log-strategy=value
  System Variable	Name	audit_log_strategy
  	Variable Scope	Global
  	Dynamic Variable	No
  Permitted Values	Type	enumeration
  	Default	ASYNCHRONOUS
  	Valid Values	ASYNCHRONOUS
  		PERFORMANCE
  		SEMISYNCHRONOUS
  		SYNCHRONOUS

  The logging method used by the audit log plugin. The following table describes the permitted values.

  Table 6.18 Audit Log Strategies

  Value	Meaning
  ASYNCHRONOUS	Log asynchronously, wait for space in output buffer
  PERFORMANCE	Log asynchronously, drop request if insufficient space in output buffer
  SEMISYNCHRONOUS	Log synchronously, permit caching by operating system
  SYNCHRONOUS	Log synchronously, call sync() after each request

  
  

6.5.4.6.3 Audit Log Plugin Status Variables

If the audit_log plugin is enabled, it exposes several status variables that provide operational information.

• 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

  The size of the largest dropped event in performance logging mode. For a description of logging modes, see Section 6.5.4.4, “Audit Log Logging Control”.

• 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.5.4.4, “Audit Log Logging Control”).

• 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.5.4.4, “Audit Log Logging Control”).

• Audit_log_events_lost

  The number of events lost in performance logging mode because an event was larger than than the available audit log buffer space. This value may be useful for assessing how to set audit_log_buffer_size to size the buffer for performance mode. For a description of logging modes, see Section 6.5.4.4, “Audit Log Logging Control”.

• Audit_log_events_written

  The number of events written to the audit log.

• Audit_log_total_size

  The total size of events written to all audit log files. Unlike Audit_log_current_size, the value of Audit_log_total_size increases even when the log is rotated.

• 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.5.4.4, “Audit Log Logging Control”.