This section describes how the audit_log
plugin performs logging and the system variables that control
how logging occurs. It assumes familiarity with the log file
format described in Section 6.5.2.3, “The Audit Log File”.
When the audit log plugin opens its log file, it checks whether
the XML declaration and opening <AUDIT>
root element tag must be written and writes them if so. When the
audit log plugin terminates, it writes a closing
</AUDIT> tag to the file.
If the log file exists at open time, the plugin checks whether
the file ends with an </AUDIT> tag and
truncates it if so before writing any
<AUDIT_RECORD> elements. If the log
file exists but does not end with
</AUDIT> or the
</AUDIT> tag cannot be truncated, the
plugin considers the file malformed and fails to initialize.
This can occur if the server crashes or is killed with the audit
log plugin running. No logging occurs until the problem is
rectified. Check the error log for diagnostic information:
[ERROR] Plugin 'audit_log' init function returned error.
To deal with this problem, either remove or rename the malformed log file and restart the server.
The MySQL server calls the audit log plugin to write an
<AUDIT_RECORD> element whenever an
auditable event occurs, such as when it completes execution of
an SQL statement received from a client. Typically the first
<AUDIT_RECORD> element written after
server startup has the server description and startup options.
Elements following that one represent events such as client
connect and disconnect events, executed SQL statements, and so
forth. Only top-level statements are logged, not statements
within stored programs such as triggers or stored procedures.
Contents of files referenced by statements such as
LOAD DATA
INFILE are not logged.
To permit control over how logging occurs, the
audit_log plugin provides several system
variables, described following. For more information, see
Section 6.5.2.7, “Audit Log Options and System Variables”.
To control the audit log file name, set the
audit_log_file system
variable at server startup. By default, the name is
audit.log in the server data 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.
The audit log plugin can use any of several strategies for log
writes. To specify a strategy, set the
audit_log_strategy system
variable at server startup. By default, the strategy value is
ASYNCHRONOUS and the plugin logs
asynchronously to a buffer, waiting if the buffer is full.
It's possible to tell the plugin not to wait
(PERFORMANCE) or to log synchronously,
either using file system caching
(SEMISYNCHRONOUS) or forcing output with a
sync() call after each write request
(SYNCHRONOUS).
Asynchronous logging strategy has these characteristics:
Minimal impact on server performance and scalability.
Blocking of threads that generate audit events for the shortest possible time; that is, time to allocate the buffer plus time to copy the event to the buffer.
Output goes to the buffer. A separate thread handles writes from the buffer to the log file.
A disadvantage of PERFORMANCE strategy is
that it drops events when the buffer is full. For a heavily
loaded server, it is more likely that the audit log will be
missing events.
With asynchronous logging, the integrity of the log file may
be compromised if a problem occurs during a write to the file
or if the plugin does not shut down cleanly (for example, in
the event that the server host crashes). To reduce this risk,
set audit_log_strategy to use
synchronous logging. Regardless of strategy, logging occurs on
a best-effort basis, with no guarantee of consistency.
The audit log plugin provides several system variables that enable you to manage the space used by its log files:
audit_log_buffer_size:
Set this variable at server startup to set the size of the
buffer for asynchronous logging. 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_rotate_on_size,
audit_log_flush: These
variables permit audit log file rotation and flushing. The
audit log file has the potential to grow very large and
consume a lot of disk space. To manage the space used,
either enable automatic log rotation, or manually rename
the audit file and flush the log to open a new file. The
renamed file can be removed or backed up as desired.
By default,
audit_log_rotate_on_size=0
and there is no log rotation. In this case, the audit log
plugin closes and reopens the log file when the
audit_log_flush value
changes from disabled to enabled. Log file renaming must
be done externally to the server. Suppose that you want to
maintain the three most recent log files, which cycle
through the names audit.log.1 through
audit.log.3. On Unix, perform
rotation manually like this:
From the command line, rename the current log files:
mv audit.log.2 audit.log.3 mv audit.log.1 audit.log.2 mv audit.log audit.log.1
At this point, the plugin is still writing to the
current log file, which has been renamed to
audit.log.1.
Connect to the server and flush the log file so the
plugin closes it and reopens a new
audit.log file:
SET GLOBAL audit_log_flush = ON;
If
audit_log_rotate_on_size
is greater than 0, setting
audit_log_flush has no
effect. In this case, the audit log plugin closes and
reopens its log file whenever a write to the file causes
its size to exceed the
audit_log_rotate_on_size
value. The plugin renames the original file to have a
timestamp extension. For example,
audit.log might be renamed to
audit.log.13440033615657730. The last
7 digits are a fractional second part. The first 10 digits
are a Unix timestamp value that can be interpreted using
the FROM_UNIXTIME()
function:
mysql> SELECT FROM_UNIXTIME(1344003361);
+---------------------------+
| FROM_UNIXTIME(1344003361) |
+---------------------------+
| 2012-08-03 09:16:01 |
+---------------------------+