Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 43.1Mb
PDF (A4) - 43.2Mb
Man Pages (TGZ) - 295.4Kb
Man Pages (Zip) - 400.6Kb
Info (Gzip) - 4.3Mb
Info (Zip) - 4.3Mb
Excerpts from this Manual

8.4.5.4 Audit Log File Formats

The MySQL server calls the audit log plugin to write an audit record to its log file whenever an auditable event occurs. Typically the first audit record written after plugin startup contains 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 are not logged.

To select the log format that the audit log plugin uses to write its log file, set the audit_log_format system variable at server startup. These formats are available:

  • New-style XML format (audit_log_format=NEW): An XML format that has better compatibility with Oracle Audit Vault than old-style XML format. MySQL 8.0 uses new-style XML format by default.

  • Old-style XML format (audit_log_format=OLD): The original audit log format used by default in older MySQL series.

  • JSON format (audit_log_format=JSON): Writes the audit log as a JSON array. Only this format supports the optional query time and size statistics, which are available from MySQL 8.0.30.

By default, audit log file contents are written in new-style XML format, without compression or encryption.

If you change audit_log_format, it is recommended that you also change audit_log_file. For example, if you set audit_log_format to JSON, set audit_log_file to audit.json. Otherwise, newer log files will have a different format than older files, but they will all have the same base name with nothing to indicate when the format changed.

New-Style XML Audit Log File Format

Here is a sample log file in new-style XML format (audit_log_format=NEW), reformatted slightly for readability:

<?xml version="1.0" encoding="utf-8"?>
<AUDIT>
 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:06:33 UTC</TIMESTAMP>
  <RECORD_ID>1_2019-10-03T14:06:33</RECORD_ID>
  <NAME>Audit</NAME>
  <SERVER_ID>1</SERVER_ID>
  <VERSION>1</VERSION>
  <STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld
    --socket=/usr/local/mysql/mysql.sock
    --port=3306</STARTUP_OPTIONS>
  <OS_VERSION>i686-Linux</OS_VERSION>
  <MYSQL_VERSION>5.7.21-log</MYSQL_VERSION>
 </AUDIT_RECORD>
 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:09:38 UTC</TIMESTAMP>
  <RECORD_ID>2_2019-10-03T14:06:33</RECORD_ID>
  <NAME>Connect</NAME>
  <CONNECTION_ID>5</CONNECTION_ID>
  <STATUS>0</STATUS>
  <STATUS_CODE>0</STATUS_CODE>
  <USER>root</USER>
  <OS_LOGIN/>
  <HOST>localhost</HOST>
  <IP>127.0.0.1</IP>
  <COMMAND_CLASS>connect</COMMAND_CLASS>
  <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
  <CONNECTION_ATTRIBUTES>
   <ATTRIBUTE>
    <NAME>_pid</NAME>
    <VALUE>42794</VALUE>
   </ATTRIBUTE>
   ...
   <ATTRIBUTE>
    <NAME>program_name</NAME>
    <VALUE>mysqladmin</VALUE>
   </ATTRIBUTE>
  </CONNECTION_ATTRIBUTES>
  <PRIV_USER>root</PRIV_USER>
  <PROXY_USER/>
  <DB>test</DB>
 </AUDIT_RECORD>

...

 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:09:38 UTC</TIMESTAMP>
  <RECORD_ID>6_2019-10-03T14:06:33</RECORD_ID>
  <NAME>Query</NAME>
  <CONNECTION_ID>5</CONNECTION_ID>
  <STATUS>0</STATUS>
  <STATUS_CODE>0</STATUS_CODE>
  <USER>root[root] @ localhost [127.0.0.1]</USER>
  <OS_LOGIN/>
  <HOST>localhost</HOST>
  <IP>127.0.0.1</IP>
  <COMMAND_CLASS>drop_table</COMMAND_CLASS>
  <SQLTEXT>DROP TABLE IF EXISTS t</SQLTEXT>
 </AUDIT_RECORD>

...

 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:09:39 UTC</TIMESTAMP>
  <RECORD_ID>8_2019-10-03T14:06:33</RECORD_ID>
  <NAME>Quit</NAME>
  <CONNECTION_ID>5</CONNECTION_ID>
  <STATUS>0</STATUS>
  <STATUS_CODE>0</STATUS_CODE>
  <USER>root</USER>
  <OS_LOGIN/>
  <HOST>localhost</HOST>
  <IP>127.0.0.1</IP>
  <COMMAND_CLASS>connect</COMMAND_CLASS>
  <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
 </AUDIT_RECORD>

...

 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:09:43 UTC</TIMESTAMP>
  <RECORD_ID>11_2019-10-03T14:06:33</RECORD_ID>
  <NAME>Quit</NAME>
  <CONNECTION_ID>6</CONNECTION_ID>
  <STATUS>0</STATUS>
  <STATUS_CODE>0</STATUS_CODE>
  <USER>root</USER>
  <OS_LOGIN/>
  <HOST>localhost</HOST>
  <IP>127.0.0.1</IP>
  <COMMAND_CLASS>connect</COMMAND_CLASS>
  <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
 </AUDIT_RECORD>
 <AUDIT_RECORD>
  <TIMESTAMP>2019-10-03T14:09:45 UTC</TIMESTAMP>
  <RECORD_ID>12_2019-10-03T14:06:33</RECORD_ID>
  <NAME>NoAudit</NAME>
  <SERVER_ID>1</SERVER_ID>
 </AUDIT_RECORD>
</AUDIT>

The audit log file is written as XML, using UTF-8 (up to 4 bytes per character). The root element is <AUDIT>. The root element contains <AUDIT_RECORD> elements, each of which provides information about an audited event. When the audit log plugin begins writing a new log file, it writes the XML declaration and opening <AUDIT> root element tag. When the plugin closes a log file, it writes the closing </AUDIT> root element tag. The closing tag is not present while the file is open.

Elements within <AUDIT_RECORD> elements have these characteristics:

  • Some elements appear in every <AUDIT_RECORD> element. Others are optional and may appear depending on the audit record type.

  • Order of elements within an <AUDIT_RECORD> element is not guaranteed.

  • Element values are not fixed length. Long values may be truncated as indicated in the element descriptions given later.

  • The <, >, ", and & characters are encoded as &lt;, &gt;, &quot;, and &amp;, respectively. NUL bytes (U+00) are encoded as the ? character.

  • Characters not valid as XML characters are encoded using numeric character references. Valid XML characters are:

    #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

The following elements are mandatory in every <AUDIT_RECORD> element:

  • <NAME>

    A string representing the type of instruction that generated the audit event, such as a command that the server received from a client.

    Example:

    <NAME>Query</NAME>

    Some common <NAME> values:

    Audit    When auditing starts, which may be server startup time
    Connect  When a client connects, also known as logging in
    Query    An SQL statement (executed directly)
    Prepare  Preparation of an SQL statement; usually followed by Execute
    Execute  Execution of an SQL statement; usually follows Prepare
    Shutdown Server shutdown
    Quit     When a client disconnects
    NoAudit  Auditing has been turned off

    The possible values are Audit, Binlog Dump, Change user, Close stmt, Connect Out, Connect, Create DB, Daemon, Debug, Delayed insert, Drop DB, Execute, Fetch, Field List, Init DB, Kill, Long Data, NoAudit, Ping, Prepare, Processlist, Query, Quit, Refresh, Register Slave, Reset stmt, Set option, Shutdown, Sleep, Statistics, Table Dump, TableDelete, TableInsert, TableRead, TableUpdate, Time.

    Many of these values correspond to the COM_xxx command values listed in the my_command.h header file. For example, Create DB and Change user correspond to COM_CREATE_DB and COM_CHANGE_USER, respectively.

    Events having <NAME> values of TableXXX accompany Query events. For example, the following statement generates one Query event, two TableRead events, and a TableInsert events:

    INSERT INTO t3 SELECT t1.* FROM t1 JOIN t2;

    Each TableXXX event contains <TABLE> and <DB> elements to identify the table to which the event refers and the database that contains the table.

  • <RECORD_ID>

    A unique identifier for the audit record. The value is composed from a sequence number and timestamp, in the format SEQ_TIMESTAMP. When the audit log plugin opens the audit log file, it initializes the sequence number to the size of the audit log file, then increments the sequence by 1 for each record logged. The timestamp is a UTC value in YYYY-MM-DDThh:mm:ss format indicating the date and time when the audit log plugin opened the file.

    Example:

    <RECORD_ID>12_2019-10-03T14:06:33</RECORD_ID>
  • <TIMESTAMP>

    A string representing a UTC value in YYYY-MM-DDThh:mm:ss UTC format indicating the date and time when the audit event was generated. For example, the event corresponding to execution of an SQL statement received from a client has a <TIMESTAMP> value occurring after the statement finishes, not when it was received.

    Example:

    <TIMESTAMP>2019-10-03T14:09:45 UTC</TIMESTAMP>

The following elements are optional in <AUDIT_RECORD> elements. Many of them occur only with specific <NAME> element values.

  • <COMMAND_CLASS>

    A string that indicates the type of action performed.

    Example:

    <COMMAND_CLASS>drop_table</COMMAND_CLASS>

    The values correspond to the statement/sql/xxx command counters. For example, xxx is drop_table and select for DROP TABLE and SELECT statements, respectively. The following statement displays the possible names:

    SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
    FROM performance_schema.events_statements_summary_global_by_event_name
    WHERE EVENT_NAME LIKE 'statement/sql/%'
    ORDER BY name;
  • <CONNECTION_ATTRIBUTES>

    As of MySQL 8.0.19, events with a <COMMAND_CLASS> value of connect may include a <CONNECTION_ATTRIBUTES> element to display the connection attributes passed by the client at connect time. (For information about these attributes, which are also exposed in Performance Schema tables, see Section 29.12.9, “Performance Schema Connection Attribute Tables”.)

    The <CONNECTION_ATTRIBUTES> element contains one <ATTRIBUTE> element per attribute, each of which contains <NAME> and <VALUE> elements to indicate the attribute name and value, respectively.

    Example:

    <CONNECTION_ATTRIBUTES>
     <ATTRIBUTE>
      <NAME>_pid</NAME>
      <VALUE>42794</VALUE>
     </ATTRIBUTE>
     <ATTRIBUTE>
      <NAME>_os</NAME>
      <VALUE>macos0.14</VALUE>
     </ATTRIBUTE>
     <ATTRIBUTE>
      <NAME>_platform</NAME>
      <VALUE>x86_64</VALUE>
     </ATTRIBUTE>
     <ATTRIBUTE>
      <NAME>_client_version</NAME>
      <VALUE>8.0.19</VALUE>
     </ATTRIBUTE>
     <ATTRIBUTE>
      <NAME>_client_name</NAME>
      <VALUE>libmysql</VALUE>
     </ATTRIBUTE>
     <ATTRIBUTE>
      <NAME>program_name</NAME>
      <VALUE>mysqladmin</VALUE>
     </ATTRIBUTE>
    </CONNECTION_ATTRIBUTES>

    If no connection attributes are present in the event, none are logged and no <CONNECTION_ATTRIBUTES> element appears. This can occur if the connection attempt is unsuccessful, the client passes no attributes, or the connection occurs internally such as during server startup or when initiated by a plugin.

  • <CONNECTION_ID>

    An unsigned integer representing the client connection identifier. This is the same as the value returned by the CONNECTION_ID() function within the session.

    Example:

    <CONNECTION_ID>127</CONNECTION_ID>
  • <CONNECTION_TYPE>

    The security state of the connection to the server. Permitted values are TCP/IP (TCP/IP connection established without encryption), SSL/TLS (TCP/IP connection established with encryption), Socket (Unix socket file connection), Named Pipe (Windows named pipe connection), and Shared Memory (Windows shared memory connection).

    Example:

    <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
  • <DB>

    A string representing a database name.

    Example:

    <DB>test</DB>

    For connect events, this element indicates the default database; the element is empty if there is no default database. For table-access events, the element indicates the database to which the accessed table belongs.

  • <HOST>

    A string representing the client host name.

    Example:

    <HOST>localhost</HOST>
  • <IP>

    A string representing the client IP address.

    Example:

    <IP>127.0.0.1</IP>
  • <MYSQL_VERSION>

    A string representing the MySQL server version. This is the same as the value of the VERSION() function or version system variable.

    Example:

    <MYSQL_VERSION>5.7.21-log</MYSQL_VERSION>
  • <OS_LOGIN>

    A string representing the external user name used during the authentication process, as set by the plugin used to authenticate the client. With native (built-in) MySQL authentication, or if the plugin does not set the value, this element is empty. The value is the same as that of the external_user system variable (see Section 8.2.19, “Proxy Users”).

    Example:

    <OS_LOGIN>jeffrey</OS_LOGIN>
  • <OS_VERSION>

    A string representing the operating system on which the server was built or is running.

    Example:

    <OS_VERSION>x86_64-Linux</OS_VERSION>
  • <PRIV_USER>

    A string representing the user that the server authenticated the client as. This is the user name that the server uses for privilege checking, and may differ from the <USER> value.

    Example:

    <PRIV_USER>jeffrey</PRIV_USER>
  • <PROXY_USER>

    A string representing the proxy user (see Section 8.2.19, “Proxy Users”). The value is empty if user proxying is not in effect.

    Example:

    <PROXY_USER>developer</PROXY_USER>
  • <SERVER_ID>

    An unsigned integer representing the server ID. This is the same as the value of the server_id system variable.

    Example:

    <SERVER_ID>1</SERVER_ID>
  • <SQLTEXT>

    A string representing the text of an SQL statement. The value can be empty. Long values may be truncated. The string, like the audit log file itself, is written using UTF-8 (up to 4 bytes per character), so the value may be the result of conversion. For example, the original statement might have been received from the client as an SJIS string.

    Example:

    <SQLTEXT>DELETE FROM t1</SQLTEXT>
  • <STARTUP_OPTIONS>

    A string representing the options that were given on the command line or in option files when the MySQL server was started. The first option is the path to the server executable.

    Example:

    <STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld
      --port=3306 --log_output=FILE</STARTUP_OPTIONS>
  • <STATUS>

    An unsigned integer representing the command status: 0 for success, nonzero if an error occurred. This is the same as the value of the mysql_errno() C API function. See the description for <STATUS_CODE> for information about how it differs from <STATUS>.

    The audit log does not contain the SQLSTATE value or error message. To see the associations between error codes, SQLSTATE values, and messages, see Server Error Message Reference.

    Warnings are not logged.

    Example:

    <STATUS>1051</STATUS>
  • <STATUS_CODE>

    An unsigned integer representing the command status: 0 for success, 1 if an error occurred.

    The STATUS_CODE value differs from the STATUS value: STATUS_CODE is 0 for success and 1 for error, which is compatible with the EZ_collector consumer for Audit Vault. STATUS is the value of the mysql_errno() C API function. This is 0 for success and nonzero for error, and thus is not necessarily 1 for error.

    Example:

    <STATUS_CODE>0</STATUS_CODE>
  • <TABLE>

    A string representing a table name.

    Example:

    <TABLE>t3</TABLE>
  • <USER>

    A string representing the user name sent by the client. This may differ from the <PRIV_USER> value.

    Example:

    <USER>root[root] @ localhost [127.0.0.1]</USER>
  • <VERSION>

    An unsigned integer representing the version of the audit log file format.

    Example:

    <VERSION>1</VERSION>
Old-Style XML Audit Log File Format

Here is a sample log file in old-style XML format (audit_log_format=OLD), reformatted slightly for readability:

<?xml version="1.0" encoding="utf-8"?>
<AUDIT>
  <AUDIT_RECORD
    TIMESTAMP="2019-10-03T14:25:00 UTC"
    RECORD_ID="1_2019-10-03T14:25:00"
    NAME="Audit"
    SERVER_ID="1"
    VERSION="1"
    STARTUP_OPTIONS="--port=3306"
    OS_VERSION="i686-Linux"
    MYSQL_VERSION="5.7.21-log"/>
  <AUDIT_RECORD
    TIMESTAMP="2019-10-03T14:25:24 UTC"
    RECORD_ID="2_2019-10-03T14:25:00"
    NAME="Connect"
    CONNECTION_ID="4"
    STATUS="0"
    STATUS_CODE="0"
    USER="root"
    OS_LOGIN=""
    HOST="localhost"
    IP="127.0.0.1"
    COMMAND_CLASS="connect"
    CONNECTION_TYPE="SSL/TLS"
    PRIV_USER="root"
    PROXY_USER=""
    DB="test"/>

...

  <AUDIT_RECORD
    TIMESTAMP="2019-10-03T14:25:24 UTC"
    RECORD_ID="6_2019-10-03T14:25:00"
    NAME="Query"
    CONNECTION_ID="4"
    STATUS="0"
    STATUS_CODE="0"
    USER="root[root] @ localhost [127.0.0.1]"
    OS_LOGIN=""
    HOST="localhost"
    IP="127.0.0.1"
    COMMAND_CLASS="drop_table"
    SQLTEXT="DROP TABLE IF EXISTS t"/>

...

  <AUDIT_RECORD
    TIMESTAMP="2019-10-03T14:25:24 UTC"
    RECORD_ID="8_2019-10-03T14:25:00"
    NAME="Quit"
    CONNECTION_ID="4"
    STATUS="0"
    STATUS_CODE="0"
    USER="root"
    OS_LOGIN=""
    HOST="localhost"
    IP="127.0.0.1"
    COMMAND_CLASS="connect"
    CONNECTION_TYPE="SSL/TLS"/>
  <AUDIT_RECORD
    TIMESTAMP="2019-10-03T14:25:32 UTC"
    RECORD_ID="12_2019-10-03T14:25:00"
    NAME="NoAudit"
    SERVER_ID="1"/>
</AUDIT>

The audit log file is written as XML, using UTF-8 (up to 4 bytes per character). The root element is <AUDIT>. The root element contains <AUDIT_RECORD> elements, each of which provides information about an audited event. When the audit log plugin begins writing a new log file, it writes the XML declaration and opening <AUDIT> root element tag. When the plugin closes a log file, it writes the closing </AUDIT> root element tag. The closing tag is not present while the file is open.

Attributes of <AUDIT_RECORD> elements have these characteristics:

  • Some attributes appear in every <AUDIT_RECORD> element. Others are optional and may appear depending on the audit record type.

  • Order of attributes within an <AUDIT_RECORD> element is not guaranteed.

  • Attribute values are not fixed length. Long values may be truncated as indicated in the attribute descriptions given later.

  • The <, >, ", and & characters are encoded as &lt;, &gt;, &quot;, and &amp;, respectively. NUL bytes (U+00) are encoded as the ? character.

  • Characters not valid as XML characters are encoded using numeric character references. Valid XML characters are:

    #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

The following attributes are mandatory in every <AUDIT_RECORD> element:

  • NAME

    A string representing the type of instruction that generated the audit event, such as a command that the server received from a client.

    Example: NAME="Query"

    Some common NAME values:

    Audit    When auditing starts, which may be server startup time
    Connect  When a client connects, also known as logging in
    Query    An SQL statement (executed directly)
    Prepare  Preparation of an SQL statement; usually followed by Execute
    Execute  Execution of an SQL statement; usually follows Prepare
    Shutdown Server shutdown
    Quit     When a client disconnects
    NoAudit  Auditing has been turned off

    The possible values are Audit, Binlog Dump, Change user, Close stmt, Connect Out, Connect, Create DB, Daemon, Debug, Delayed insert, Drop DB, Execute, Fetch, Field List, Init DB, Kill, Long Data, NoAudit, Ping, Prepare, Processlist, Query, Quit, Refresh, Register Slave, Reset stmt, Set option, Shutdown, Sleep, Statistics, Table Dump, TableDelete, TableInsert, TableRead, TableUpdate, Time.

    Many of these values correspond to the COM_xxx command values listed in the my_command.h header file. For example, "Create DB" and "Change user" correspond to COM_CREATE_DB and COM_CHANGE_USER, respectively.

    Events having NAME values of TableXXX accompany Query events. For example, the following statement generates one Query event, two TableRead events, and a TableInsert events:

    INSERT INTO t3 SELECT t1.* FROM t1 JOIN t2;

    Each TableXXX event has TABLE and DB attributes to identify the table to which the event refers and the database that contains the table.

    Connect events for old-style XML audit log format do not include connection attributes.

  • RECORD_ID

    A unique identifier for the audit record. The value is composed from a sequence number and timestamp, in the format SEQ_TIMESTAMP. When the audit log plugin opens the audit log file, it initializes the sequence number to the size of the audit log file, then increments the sequence by 1 for each record logged. The timestamp is a UTC value in YYYY-MM-DDThh:mm:ss format indicating the date and time when the audit log plugin opened the file.

    Example: RECORD_ID="12_2019-10-03T14:25:00"

  • TIMESTAMP

    A string representing a UTC value in YYYY-MM-DDThh:mm:ss UTC format indicating the date and time when the audit event was generated. For example, the event corresponding to execution of an SQL statement received from a client has a TIMESTAMP value occurring after the statement finishes, not when it was received.

    Example: TIMESTAMP="2019-10-03T14:25:32 UTC"

The following attributes are optional in <AUDIT_RECORD> elements. Many of them occur only for elements with specific values of the NAME attribute.

  • COMMAND_CLASS

    A string that indicates the type of action performed.

    Example: COMMAND_CLASS="drop_table"

    The values correspond to the statement/sql/xxx command counters. For example, xxx is drop_table and select for DROP TABLE and SELECT statements, respectively. The following statement displays the possible names:

    SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
    FROM performance_schema.events_statements_summary_global_by_event_name
    WHERE EVENT_NAME LIKE 'statement/sql/%'
    ORDER BY name;
  • CONNECTION_ID

    An unsigned integer representing the client connection identifier. This is the same as the value returned by the CONNECTION_ID() function within the session.

    Example: CONNECTION_ID="127"

  • CONNECTION_TYPE

    The security state of the connection to the server. Permitted values are TCP/IP (TCP/IP connection established without encryption), SSL/TLS (TCP/IP connection established with encryption), Socket (Unix socket file connection), Named Pipe (Windows named pipe connection), and Shared Memory (Windows shared memory connection).

    Example: CONNECTION_TYPE="SSL/TLS"

  • DB

    A string representing a database name.

    Example: DB="test"

    For connect events, this attribute indicates the default database; the attribute is empty if there is no default database. For table-access events, the attribute indicates the database to which the accessed table belongs.

  • HOST

    A string representing the client host name.

    Example: HOST="localhost"

  • IP

    A string representing the client IP address.

    Example: IP="127.0.0.1"

  • MYSQL_VERSION

    A string representing the MySQL server version. This is the same as the value of the VERSION() function or version system variable.

    Example: MYSQL_VERSION="5.7.21-log"

  • OS_LOGIN

    A string representing the external user name used during the authentication process, as set by the plugin used to authenticate the client. With native (built-in) MySQL authentication, or if the plugin does not set the value, this attribute is empty. The value is the same as that of the external_user system variable (see Section 8.2.19, “Proxy Users”).

    Example: OS_LOGIN="jeffrey"

  • OS_VERSION

    A string representing the operating system on which the server was built or is running.

    Example: OS_VERSION="x86_64-Linux"

  • PRIV_USER

    A string representing the user that the server authenticated the client as. This is the user name that the server uses for privilege checking, and it may differ from the USER value.

    Example: PRIV_USER="jeffrey"

  • PROXY_USER

    A string representing the proxy user (see Section 8.2.19, “Proxy Users”). The value is empty if user proxying is not in effect.

    Example: PROXY_USER="developer"

  • SERVER_ID

    An unsigned integer representing the server ID. This is the same as the value of the server_id system variable.

    Example: SERVER_ID="1"

  • SQLTEXT

    A string representing the text of an SQL statement. The value can be empty. Long values may be truncated. The string, like the audit log file itself, is written using UTF-8 (up to 4 bytes per character), so the value may be the result of conversion. For example, the original statement might have been received from the client as an SJIS string.

    Example: SQLTEXT="DELETE FROM t1"

  • STARTUP_OPTIONS

    A string representing the options that were given on the command line or in option files when the MySQL server was started.

    Example: STARTUP_OPTIONS="--port=3306 --log_output=FILE"

  • STATUS

    An unsigned integer representing the command status: 0 for success, nonzero if an error occurred. This is the same as the value of the mysql_errno() C API function. See the description for STATUS_CODE for information about how it differs from STATUS.

    The audit log does not contain the SQLSTATE value or error message. To see the associations between error codes, SQLSTATE values, and messages, see Server Error Message Reference.

    Warnings are not logged.

    Example: STATUS="1051"

  • STATUS_CODE

    An unsigned integer representing the command status: 0 for success, 1 if an error occurred.

    The STATUS_CODE value differs from the STATUS value: STATUS_CODE is 0 for success and 1 for error, which is compatible with the EZ_collector consumer for Audit Vault. STATUS is the value of the mysql_errno() C API function. This is 0 for success and nonzero for error, and thus is not necessarily 1 for error.

    Example: STATUS_CODE="0"

  • TABLE

    A string representing a table name.

    Example: TABLE="t3"

  • USER

    A string representing the user name sent by the client. This may differ from the PRIV_USER value.

  • VERSION

    An unsigned integer representing the version of the audit log file format.

    Example: VERSION="1"

JSON Audit Log File Format

For JSON-format audit logging (audit_log_format=JSON), the log file contents form a JSON array with each array element representing an audited event as a JSON hash of key-value pairs. Examples of complete event records appear later in this section. The following is an excerpt of partial events:

[
  {
    "timestamp": "2019-10-03 13:50:01",
    "id": 0,
    "class": "audit",
    "event": "startup",
    ...
  },
  {
    "timestamp": "2019-10-03 15:02:32",
    "id": 0,
    "class": "connection",
    "event": "connect",
    ...
  },
  ...
  {
    "timestamp": "2019-10-03 17:37:26",
    "id": 0,
    "class": "table_access",
    "event": "insert",
      ...
  }
  ...
]

The audit log file is written using UTF-8 (up to 4 bytes per character). When the audit log plugin begins writing a new log file, it writes the opening [ array marker. When the plugin closes a log file, it writes the closing ] array marker. The closing marker is not present while the file is open.

Items within audit records have these characteristics:

  • Some items appear in every audit record. Others are optional and may appear depending on the audit record type.

  • Order of items within an audit record is not guaranteed.

  • Item values are not fixed length. Long values may be truncated as indicated in the item descriptions given later.

  • The " and \ characters are encoded as \" and \\, respectively.

JSON format is the only audit log file format that supports the optional query time and size statistics, which are available from MySQL 8.0.30. This data is available in the slow query log for qualifying queries, and in the context of the audit log it similarly helps to detect outliers for activity analysis.

To add the query statistics to the log file, you must set them up as a filter using the audit_log_filter_set_filter() audit log function as the service element of the JSON filtering syntax. For instructions to do this, see Adding Query Statistics for Outlier Detection. For the bytes_sent and bytes_received fields to be populated, the system variable log_slow_extra must be set to ON.

The following examples show the JSON object formats for different event types (as indicated by the class and event items), reformatted slightly for readability:

Auditing startup event:

{ "timestamp": "2019-10-03 14:21:56",
  "id": 0,
  "class": "audit",
  "event": "startup",
  "connection_id": 0,
  "startup_data": { "server_id": 1,
                    "os_version": "i686-Linux",
                    "mysql_version": "5.7.21-log",
                    "args": ["/usr/local/mysql/bin/mysqld",
                             "--loose-audit-log-format=JSON",
                             "--log-error=log.err",
                             "--pid-file=mysqld.pid",
                             "--port=3306" ] } }

When the audit log plugin starts as a result of server startup (as opposed to being enabled at runtime), connection_id is set to 0, and account and login are not present.

Auditing shutdown event:

{ "timestamp": "2019-10-03 14:28:20",
  "id": 3,
  "class": "audit",
  "event": "shutdown",
  "connection_id": 0,
  "shutdown_data": { "server_id": 1 } }

When the audit log plugin is uninstalled as a result of server shutdown (as opposed to being disabled at runtime), connection_id is set to 0, and account and login are not present.

Connect or change-user event:

{ "timestamp": "2019-10-03 14:23:18",
  "id": 1,
  "class": "connection",
  "event": "connect",
  "connection_id": 5,
  "account": { "user": "root", "host": "localhost" },
  "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
  "connection_data": { "connection_type": "ssl",
                       "status": 0,
                       "db": "test",
                       "connection_attributes": {
                         "_pid": "43236",
                         ...
                         "program_name": "mysqladmin"
                       } }
}

Disconnect event:

{ "timestamp": "2019-10-03 14:24:45",
  "id": 3,
  "class": "connection",
  "event": "disconnect",
  "connection_id": 5,
  "account": { "user": "root", "host": "localhost" },
  "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
  "connection_data": { "connection_type": "ssl" } }

Query event:

{ "timestamp": "2019-10-03 14:23:35",
  "id": 2,
  "class": "general",
  "event": "status",
  "connection_id": 5,
  "account": { "user": "root", "host": "localhost" },
  "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
  "general_data": { "command": "Query",
                    "sql_command": "show_variables",
                    "query": "SHOW VARIABLES",
                    "status": 0 } }

Query event with optional query statistics for outlier detection:

{ "timestamp": "2022-01-28 13:09:30", 
  "id": 0, 
  "class": "general", 
  "event": "status", 
  "connection_id": 46, 
  "account": { "user": "user", "host": "localhost" }, 
  "login": { "user": "user", “os": "", “ip": "127.0.0.1", “proxy": "" }, 
  "general_data": { "command": "Query", 
                    "sql_command": "insert",
	            "query": "INSERT INTO audit_table VALUES(4)",
	            "status": 1146 }
  "query_statistics": { "query_time": 0.116250,
                        "bytes_sent": 18384,
                        "bytes_received": 78858,
                        "rows_sent": 3,
                        "rows_examined": 20878 } }

Table access event (read, delete, insert, update):

{ "timestamp": "2019-10-03 14:23:41",
  "id": 0,
  "class": "table_access",
  "event": "insert",
  "connection_id": 5,
  "account": { "user": "root", "host": "localhost" },
  "login": { "user": "root", "os": "", "ip": "127.0.0.1", "proxy": "" },
  "table_access_data": { "db": "test",
                         "table": "t1",
                         "query": "INSERT INTO t1 (i) VALUES(1),(2),(3)",
                         "sql_command": "insert" } }

The items in the following list appear at the top level of JSON-format audit records: Each item value is either a scalar or a JSON hash. For items that have a hash value, the description lists only the item names within that hash. For more complete descriptions of second-level hash items, see later in this section.

  • account

    The MySQL account associated with the event. The value is a hash containing these items equivalent to the value of the CURRENT_USER() function within the section: user, host.

    Example:

    "account": { "user": "root", "host": "localhost" }
  • class

    A string representing the event class. The class defines the type of event, when taken together with the event item that specifies the event subclass.

    Example:

    "class": "connection"

    The following table shows the permitted combinations of class and event values.

    Table 8.34 Audit Log Class and Event Combinations

    Class Value Permitted Event Values
    audit startup, shutdown
    connection connect, change_user, disconnect
    general status
    table_access_data read, delete, insert, update

  • connection_data

    Information about a client connection. The value is a hash containing these items: connection_type, status, db, and possibly connection_attributes. This item occurs only for audit records with a class value of connection.

    Example:

    "connection_data": { "connection_type": "ssl",
                         "status": 0,
                         "db": "test" }

    As of MySQL 8.0.19, events with a class value of connection and event value of connect may include a connection_attributes item to display the connection attributes passed by the client at connect time. (For information about these attributes, which are also exposed in Performance Schema tables, see Section 29.12.9, “Performance Schema Connection Attribute Tables”.)

    The connection_attributes value is a hash that represents each attribute by its name and value.

    Example:

    "connection_attributes": {
      "_pid": "43236",
      "_os": "macos0.14",
      "_platform": "x86_64",
      "_client_version": "8.0.19",
      "_client_name": "libmysql",
      "program_name": "mysqladmin"
    }

    If no connection attributes are present in the event, none are logged and no connection_attributes item appears. This can occur if the connection attempt is unsuccessful, the client passes no attributes, or the connection occurs internally such as during server startup or when initiated by a plugin.

  • connection_id

    An unsigned integer representing the client connection identifier. This is the same as the value returned by the CONNECTION_ID() function within the session.

    Example:

    "connection_id": 5
  • event

    A string representing the subclass of the event class. The subclass defines the type of event, when taken together with the class item that specifies the event class. For more information, see the class item description.

    Example:

    "event": "connect"
  • general_data

    Information about an executed statement or command. The value is a hash containing these items: command, sql_command, query, status. This item occurs only for audit records with a class value of general.

    Example:

    "general_data": { "command": "Query",
                      "sql_command": "show_variables",
                      "query": "SHOW VARIABLES",
                      "status": 0 }
  • id

    An unsigned integer representing an event ID.

    Example:

    "id": 2

    For audit records that have the same timestamp value, their id values distinguish them and form a sequence. Within the audit log, timestamp/id pairs are unique. These pairs are bookmarks that identify event locations within the log.

  • login

    Information indicating how a client connected to the server. The value is a hash containing these items: user, os, ip, proxy.

    Example:

    "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" }
  • query_statistics

    Optional query statistics for outlier detection. The value is a hash containing these items: query_time, rows_sent, rows_examined, bytes_received, bytes_sent. For instructions to set up the query statistics, see Adding Query Statistics for Outlier Detection.

    Example:

    "query_statistics": { "query_time": 0.116250,
                          "bytes_sent": 18384,
                          "bytes_received": 78858,
                          "rows_sent": 3,
                          "rows_examined": 20878 }
  • shutdown_data

    Information pertaining to audit log plugin termination. The value is a hash containing these items: server_id This item occurs only for audit records with class and event values of audit and shutdown, respectively.

    Example:

    "shutdown_data": { "server_id": 1 }
  • startup_data

    Information pertaining to audit log plugin initialization. The value is a hash containing these items: server_id, os_version, mysql_version, args. This item occurs only for audit records with class and event values of audit and startup, respectively.

    Example:

    "startup_data": { "server_id": 1,
                      "os_version": "i686-Linux",
                      "mysql_version": "5.7.21-log",
                      "args": ["/usr/local/mysql/bin/mysqld",
                               "--loose-audit-log-format=JSON",
                               "--log-error=log.err",
                               "--pid-file=mysqld.pid",
                               "--port=3306" ] }
  • table_access_data

    Information about an access to a table. The value is a hash containing these items: db, table, query, sql_command, This item occurs only for audit records with a class value of table_access.

    Example:

    "table_access_data": { "db": "test",
                           "table": "t1",
                           "query": "INSERT INTO t1 (i) VALUES(1),(2),(3)",
                           "sql_command": "insert" }
  • time

    This field is similar to that in the timestamp field, but the value is an integer and represents the UNIX timestamp value indicating the date and time when the audit event was generated.

    Example:

    "time" : 1618498687

    The time field occurs in JSON-format log files only if the audit_log_format_unix_timestamp system variable is enabled.

  • timestamp

    A string representing a UTC value in YYYY-MM-DD hh:mm:ss format indicating the date and time when the audit event was generated. For example, the event corresponding to execution of an SQL statement received from a client has a timestamp value occurring after the statement finishes, not when it was received.

    Example:

    "timestamp": "2019-10-03 13:50:01"

    For audit records that have the same timestamp value, their id values distinguish them and form a sequence. Within the audit log, timestamp/id pairs are unique. These pairs are bookmarks that identify event locations within the log.

These items appear within hash values associated with top-level items of JSON-format audit records:

  • args

    An array of options that were given on the command line or in option files when the MySQL server was started. The first option is the path to the server executable.

    Example:

    "args": ["/usr/local/mysql/bin/mysqld",
             "--loose-audit-log-format=JSON",
             "--log-error=log.err",
             "--pid-file=mysqld.pid",
             "--port=3306" ]
  • bytes_received

    The number of bytes received from the client. This item is part of the optional query statistics. For this field to be populated, the system variable log_slow_extra must be set to ON.

    Example:

    "bytes_received": 78858
  • bytes_sent

    The number of bytes sent to the client. This item is part of the optional query statistics. For this field to be populated, the system variable log_slow_extra must be set to ON.

    Example:

    "bytes_sent": 18384
  • command

    A string representing the type of instruction that generated the audit event, such as a command that the server received from a client.

    Example:

    "command": "Query"
  • connection_type

    The security state of the connection to the server. Permitted values are tcp/ip (TCP/IP connection established without encryption), ssl (TCP/IP connection established with encryption), socket (Unix socket file connection), named_pipe (Windows named pipe connection), and shared_memory (Windows shared memory connection).

    Example:

    "connection_type": "tcp/tcp"
  • db

    A string representing a database name. For connection_data, it is the default database. For table_access_data, it is the table database.

    Example:

    "db": "test"
  • host

    A string representing the client host name.

    Example:

    "host": "localhost"
  • ip

    A string representing the client IP address.

    Example:

    "ip": "::1"
  • mysql_version

    A string representing the MySQL server version. This is the same as the value of the VERSION() function or version system variable.

    Example:

    "mysql_version": "5.7.21-log"
  • os

    A string representing the external user name used during the authentication process, as set by the plugin used to authenticate the client. With native (built-in) MySQL authentication, or if the plugin does not set the value, this attribute is empty. The value is the same as that of the external_user system variable. See Section 8.2.19, “Proxy Users”.

    Example:

    "os": "jeffrey"
  • os_version

    A string representing the operating system on which the server was built or is running.

    Example:

    "os_version": "i686-Linux"
  • proxy

    A string representing the proxy user (see Section 8.2.19, “Proxy Users”). The value is empty if user proxying is not in effect.

    Example:

    "proxy": "developer"
  • query

    A string representing the text of an SQL statement. The value can be empty. Long values may be truncated. The string, like the audit log file itself, is written using UTF-8 (up to 4 bytes per character), so the value may be the result of conversion. For example, the original statement might have been received from the client as an SJIS string.

    Example:

    "query": "DELETE FROM t1"
  • query_time

    The query execution time in microseconds (if the longlong data type is selected) or seconds (if the double data type is selected). This item is part of the optional query statistics.

    Example:

    "query_time": 0.116250
  • rows_examined

    The number of rows accessed during the query. This item is part of the optional query statistics.

    Example:

    "rows_examined": 20878
  • rows_sent

    The number of rows sent to the client as a result. This item is part of the optional query statistics.

    Example:

    "rows_sent": 3
  • server_id

    An unsigned integer representing the server ID. This is the same as the value of the server_id system variable.

    Example:

    "server_id": 1
  • sql_command

    A string that indicates the SQL statement type.

    Example:

    "sql_command": "insert"

    The values correspond to the statement/sql/xxx command counters. For example, xxx is drop_table and select for DROP TABLE and SELECT statements, respectively. The following statement displays the possible names:

    SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
    FROM performance_schema.events_statements_summary_global_by_event_name
    WHERE EVENT_NAME LIKE 'statement/sql/%'
    ORDER BY name;
  • status

    An unsigned integer representing the command status: 0 for success, nonzero if an error occurred. This is the same as the value of the mysql_errno() C API function.

    The audit log does not contain the SQLSTATE value or error message. To see the associations between error codes, SQLSTATE values, and messages, see Server Error Message Reference.

    Warnings are not logged.

    Example:

    "status": 1051
  • table

    A string representing a table name.

    Example:

    "table": "t1"
  • user

    A string representing a user name. The meaning differs depending on the item within which user occurs:

    • Within account items, user is a string representing the user that the server authenticated the client as. This is the user name that the server uses for privilege checking.

    • Within login items, user is a string representing the user name sent by the client.

    Example:

    "user": "root"