Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 33.3Mb
PDF (A4) - 33.3Mb
PDF (RPM) - 31.3Mb
HTML Download (TGZ) - 7.9Mb
HTML Download (Zip) - 8.0Mb
HTML Download (RPM) - 6.8Mb
Man Pages (TGZ) - 144.9Kb
Man Pages (Zip) - 205.9Kb
Info (Gzip) - 3.0Mb
Info (Zip) - 3.0Mb


Pre-General Availability Draft: 2017-09-20

5.4.2 The Error Log

This section discusses how to configure the MySQL server for logging of diagnostic messages to the error log. For information about selecting the error message character set or language, see Section 10.1.6, “Error Message Character Set”, or Section 10.2, “Setting the Error Message Language”.

The error log contains a record of mysqld startup and shutdown times. It also contains diagnostic messages such as errors, warnings, and notes that occur during server startup and shutdown, and while the server is running. For example, if mysqld notices that a table needs to be automatically checked or repaired, it writes a message to the error log.

On some operating systems, the error log contains a stack trace if mysqld exits abnormally. The trace can be used to determine where mysqld exited. See Section 28.5, “Debugging and Porting MySQL”.

If used to start mysqld, mysqld_safe may write messages to the error log. For example, when mysqld_safe notices abnormal mysqld exits, it restarts mysqld and writes a mysqld restarted message to the error log.

The following sections discuss aspects of configuring error logging:

Error Log Component Configuration

In MySQL 8.0, error logging uses the MySQL component architecture described at Section 5.5, “MySQL Server Components”. The error log subsystem consists of components that perform log event filtering and writing, as well as a system variable that configures which components to enable to achieve the desired logging result.

This section discusses how to select components for error logging. For instructions specific to the system log and JSON log writers, see Error Logging to the System Log, and Error Logging in JSON Format. For additional details about all available log components, see Section 5.5.1, “Error Log Components”.

Component-based error logging offers these features:

  • Log events can be filtered by filter components to affect the information available for writing.

  • Log events are output by sink (writer) components. Multiple sink components can be enabled, to write error log output to multiple destinations.

  • Built-in filter and writer components combine to implement the default error logging format.

  • A loadable writer enables logging to the system log.

  • A loadable writer enables logging in JSON format.

  • A system variable controls which log components to enable.

The log_error_services system variable controls which log components to enable for error logging. Its value is a list of semicolon-separated components. Spaces are not significant. Component order is significant because the server executes components in the order listed.

By default, log_error_services has this value:

mysql> SELECT @@global.log_error_services;
+----------------------------------------+
| @@global.log_error_services            |
+----------------------------------------+
| log_filter_internal; log_sink_internal |
+----------------------------------------+

That value indicates that log events first pass through the built-in filter component, log_filter_internal, then through the built-in log writer component, log_sink_internal. A filter modifies log events seen by components named later in the log_error_services value. A sink is a destination for log events. Typically, a sink processes log events into log messages that have a particular format and writes these messages to its associated output, such as a file or the system log.

Note

If log_error_services is assigned a value that contains no writer components, no log output is written from that point.

The combination of log_filter_internal and log_sink_internal implements the default error log filtering and output behavior. The action of these components is affected by other server options and system variables:

To change the set of log components used for error logging, load components as necessary and modify the log_error_services value. Adding or removing log components is subject to these constraints:

For example, to use the system log writer (log_sink_syseventlog) instead of the default writer (log_sink_internal), first load the writer component, then modify the log_error_services value:

INSTALL COMPONENT 'file://component_log_sink_syseventlog';
SET GLOBAL log_error_services = 'log_filter_internal; log_sink_syseventlog';
Note

The URN to use for loading a log component with INSTALL COMPONENT is the component name prefixed with file://component_. For example, for the log_sink_syseventlog component, the corresponding URN is file://component_log_sink_syseventlog.

It is possible to configure multiple log writers to send output to multiple destinations. To use the system log writer in addition to (rather than instead of) the default writer, set the log_error_services value like this:

SET GLOBAL log_error_services = 'log_filter_internal; log_sink_internal; log_sink_syseventlog';

To revert to using only the default writer and unload the system log writer, execute these statements:

SET GLOBAL log_error_services = 'log_filter_internal; log_sink_internal;
UNINSTALL COMPONENT 'file://component_log_sink_syseventlog';

To configure a log component to be enabled at each server startup, use this procedure:

  1. If the component is loadable, load it using INSTALL COMPONENT. Loading the component registers it in the mysql.component system table so that the server loads it automatically for subsequent startups.

  2. Set the log_error_services value at startup to include the component name. Set the value either in the server my.cnf file, or use SET PERSIST, which sets the value for the running MySQL instance and also saves the value to be used for subsequent server restarts; see Section 13.7.4.1, “SET Syntax for Variable Assignment”. A value set in my.cnf takes effect at the next restart. A value set using SET PERSIST takes effect immediately, and for subsequent restarts.

Suppose that you want to configure, for every server startup, use of the JSON log writer (log_sink_json) in addition to the built-in log filter and writer (log_filter_internal, log_sink_internal). First load the JSON writer if it is not loaded:

INSTALL COMPONENT 'file://component_log_sink_json';

Then set log_error_services to take effect at server startup. You can set it in my.cnf:

[mysqld]
log_error_services='log_filter_internal; log_sink_internal; log_sink_json'

Or you can set it using SET PERSIST:

SET PERSIST log_error_services = 'log_filter_internal; log_sink_internal; log_sink_json';

The order of components named in log_error_services is significant, particularly with respect to the relative order of filters and writers. Consider this log_error_services value:

log_filter_internal; log_sink_1; log_sink_2

In this case, log events pass to the built-in filter, then to the first writer, then to the second writer. Both writers receive filtered log events.

Compare that to this log_error_services value:

log_sink_1; log_filter_internal; log_sink_2

In this case, log events pass to the first writer, then to the built-in filter, then to the second writer. The first writer receives unfiltered events. The second writer receives filtered events. You might configure error logging this way if you want one log that contains messages for all log events, and another containing messages only for a subset of log events.

Default Error Log Destination Configuration

This section discusses which server options configure the default error log destination, which can be the console or a named file. It also indicates which log writer components base their own output destination on the default destination.

In this discussion, console means stderr, the standard error output. This is your terminal or console window unless the standard error output has been redirected to a different destination.

The server interprets options that determine the default error log destination somewhat differently for Windows and Unix systems. Be sure to configure the destination using the information appropriate to your platform:

After the server interprets the default error log destination options, it sets the log_error system variable to indicate the default destination, which affects where several log writer components write error messages. See How the Default Error Log Destination Affects Log Writers.

Default Error Log Destination on Windows

On Windows, mysqld uses the --log-error, --pid-file, and --console options to determine whether the default error log destination is the console or a file, and, if a file, the file name:

  • If --console is given, the default destination is the console. (--console takes precedence over --log-error if both are given, and the following items regarding --log-error do not apply.)

  • If --log-error is not given, or is given without naming a file, the default destination is a file named host_name.err in the data directory, unless the --pid-file option is specified. In that case, the file name is the PID file base name with a suffix of .err in the data directory.

  • If --log-error is given to name a file, the default destination is that file (with an .err suffix added if the name has no suffix), located under the data directory unless an absolute path name is given to specify a different location.

If the default error log destination is the console, the server sets the log_error system variable to stderr. Otherwise, the default destination is a file and the server sets log_error to the file name.

Default Error Log Destination on Unix and Unix-Like Systems

On Unix and Unix-like systems, mysqld uses the --log-error option to determine whether the default error log destination is the console or a file, and, if a file, the file name:

  • If --log-error is not given, the default destination is the console.

  • If --log-error is given without naming a file, the default destination is a file named host_name.err in the data directory.

  • If --log-error is given to name a file, the default destination is that file (with an .err suffix added if the name has no suffix), located under the data directory unless an absolute path name is given to specify a different location.

  • If --log-error is given in an option file in a [mysqld], [server], or [mysqld_safe] section, mysqld_safe finds and uses the option, and passes it to mysqld.

Note

It is common for Yum or APT package installations to configure an error log file location under /var/log with an option like log-error=/var/log/mysqld.log in a server configuration file. Removing the file name from the option causes the host_name.err file in the data directory to be used.

If the default error log destination is the console, the server sets the log_error system variable to stderr. Otherwise, the default destination is a file and the server sets log_error to the file name.

How the Default Error Log Destination Affects Log Writers

After the server interprets the error log destination configuration options, it sets the log_error system variable to indicate the default error log destination. Log writer components may base their own output destination on the log_error value, or determine their destination independently of log_error

If log_error is stderr, the default error log destination is the console, and log writers that base their output destination on the default destination also write to the console:

  • log_sink_internal, log_sink_json, log_sink_test: These writers write to the console. This is true even for writers such as log_sink_json that can be enabled multiple times; all instances write to the console.

  • log_sink_syseventlog: This writer writes to the system log, regardless of the log_error value.

If log_error is not stderr, the default error log destination is a file and log_error indicates the file name. Log writers that base their output destination on the default destination base output file naming on that file name. (A writer might use exactly that name, or it might use some variant thereof.) Suppose that the log_error value file_name. Then log writers use the name like this:

  • log_sink_internal, log_sink_test: These writers write to file_name.

  • log_sink_json: Successive instances of this writer named in the log_error_services value write to files named file_name plus a numbered .NN.json suffix: file_name.00.json, file_name.01.json, and so forth.

  • log_sink_syseventlog: This writer writes to the system log, regardless of the log_error value.

Error Logging to the System Log

It is possible to have mysqld write the error log to the system log. This is the Event Log on Windows, and syslog on Unix and Unix-like systems.

This section describes how to configure error logging using the built-in filter, log_filter_internal, and the system log writer, log_sink_syseventlog, to take effect immediately and for subsequent server startups. For general configuration about configuring error logging, see Error Log Component Configuration.

Note

In MySQL 8.0, you must configure system log error logging explicitly. This differs from MySQL 5.7 and earlier, for which logging to the system log is enabled by default on Windows, and on all platforms requires no component loading.

To use the system log writer, first load the writer component, then modify the log_error_services value:

INSTALL COMPONENT 'file://component_log_sink_syseventlog';
SET PERSIST log_error_services = 'log_filter_internal; log_sink_syseventlog';
Note

Logging to the system log may require additional system configuration. Consult the system log documentation for your platform.

On Windows, error messages written to the Event Log within the Application log have these characteristics:

  • Entries marked as Error, Warning, and Note are written to the Event Log, but not messages such as information statements from individual storage engines.

  • Event Log entries have a source of MySQL.

On Unix and Unix-like systems, logging to the system log uses syslog. The following system variables affect syslog messages:

  • log_syslog_facility: The default facility for syslog messages is daemon. Set this variable to specify a different facility.

  • log_syslog_include_pid: Whether to include the server process ID in each line of syslog output.

  • log_syslog_tag: This variable defines a tag to add to the server identifier (mysqld) in syslog messages. If defined, the tag is appended to the identifier with a leading hyphen.

Error Logging in JSON Format

This section describes how to configure error logging using the built-in filter, log_filter_internal, and the JSON writer, log_sink_json, to take effect immediately and for subsequent server startups. For general configuration about configuring error logging, see Error Log Component Configuration.

To use the JSON writer, first load the writer component, then modify the log_error_services value:

INSTALL COMPONENT 'file://component_log_sink_json';
SET PERSIST log_error_services = 'log_filter_internal; log_sink_json';

It is permitted to name log_sink_json multiple times in the log_error_services value. For example, to write unfiltered events with one instance and filtered events with another instance, you could set log_error_services like this:

SET PERSIST log_error_services = 'log_sink_json; log_filter_internal; log_sink_json';

The JSON log writer determines its output destination based on the default error log destination, which is given by the log_error system variable. If log_error names a file, the JSON writer bases output file naming on that file name, plus a numbered .NN.json suffix, with NN starting at 00. For example, if log_error is file_name, successive instances of log_sink_json named in the log_error_services value write to file_name.00.json, file_name.01.json, and so forth.

If log_error is stderr, the JSON writer writes to the console. If log_json_writer is named multiple times in the log_error_services value, they all write to the console, which is likely not useful.

Error Log Verbosity

The log_error_verbosity system variable controls server verbosity for writing error, warning, and note messages to the error log. It affects which types of log events the log_filter_internal filter component permits or suppresses, and thus has no effect if that component is not enabled.

Permitted log_error_verbosity values are 1 (errors only), 2 (errors and warnings), 3 (errors, warnings, and notes), with a default of 3.

If the variable value is greater than 2 or greater, the server logs messages about statements that are unsafe for statement-based logging. If the value is 3, the server logs aborted connections and access-denied errors for new connection attempts. See Section B.5.2.10, “Communication Errors and Aborted Connections”.

If you use replication, setting this variable to 2 or greater is recommended, to get more information about what is happening, such as messages about network failures and reconnections.

If a slave server is started with this variable set to 2 or greater, the slave prints messages to the error log to provide information about its status, such as the binary log and relay log coordinates where it starts its job, when it is switching to another relay log, when it reconnects after a disconnect, and so forth.

Error Log Message Format

Each error log sink (writer) component has a characteristic output format it uses to write messages to its destination, but other factors may influence the content of the messages:

  • The information available to the log writer. If a log filter component executed prior to execution of the writer component removes a log event attribute, that attribute is not available for writing.

  • System variables may affect log writers.

For all log writers, the ID included in error log messages is that of the thread within mysqld responsible for writing the message. This indicates which part of the server produced the message, and is consistent with general query log and slow query log messages, which include the connection thread ID.

Output Format for log_sink_internal

This log writer produces the traditional error log output. It writes messages using this format:

timestamp thread_id [severity] message

Examples:

2017-08-26T01:37:14.136034Z 0 [Warning] CA certificate /var/mysql/ssl/ca.pem is self signed.
2017-08-30T16:21:52.167838Z 0 [Note] IPv6 is available.
Output Format for log_sink_json

The JSON-format log writer produces messages as JSON objects that contain key/value pairs. For example:

{ "prio" : 2, "err_code" : 3674, "subsystem" : "event",
"source_line" : 585, "source_file" : "event_scheduler.cc", "function" : "run",
"msg" : "Event Scheduler: scheduler thread started with id 4",
"time" : "2017-08-31T18:33:25.483190Z", "thread" : 4,
"err_symbol" : "ER_SCHEDULER_STARTED", "SQL_state" : "HY000",
"label" : "Note" }
Output Format for log_sink_syseventlog

The system log writer produces output that conforms to the system log format used on the local platform.

System Variables That Affect Error Log Format

The log_timestamps system variable controls the time zone of timestamps in messages written to the error log (as well as to general query log and slow query log files). Permitted values are UTC (the default) and SYSTEM (local system time zone).

Error Log File Flushing and Renaming

If you flush the error log using FLUSH ERROR LOGS, FLUSH LOGS, or mysqladmin flush-logs, the server closes and reopens any error log file to which it is writing. To rename an error log file, do so manually before flushing. Flushing the logs then opens a new file with the original file name. For example, assuming a log file name of host_name.err, to rename the file and create a new one, use the following commands:

mv host_name.err host_name.err-old
mysqladmin flush-logs
mv host_name.err-old backup-directory

On Windows, use rename rather than mv.

If the location of an error log file is not writable by the server, the log-flushing operation fails to create a new log file. For example, on Linux, the server might write the error log to the /var/log/mysqld.log file, where the /var/log directory is owned by root and is not writable by mysqld. For information about handling this case, see Section 5.4.7, “Server Log Maintenance”.

If the server is not writing to a named error log file, no error log file renaming occurs when the error log is flushed.


User Comments
Sign Up Login You must be logged in to post a comment.