Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.2Mb
PDF (A4) - 38.3Mb
PDF (RPM) - 33.1Mb
HTML Download (TGZ) - 8.1Mb
HTML Download (Zip) - 8.1Mb
HTML Download (RPM) - 7.0Mb
Man Pages (TGZ) - 133.2Kb
Man Pages (Zip) - 189.3Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Error Log Component Configuration

5.4.2.1 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 Section 5.4.2.3, “Error Logging to the System Log”, and Section 5.4.2.4, “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.

  • System variables control which log components to enable and the rules for filtering log events.

The log_error_services system variable controls which log components to enable for error logging. The variable may contain a list with 0, 1, or many elements. In the latter case, elements may be delimited by semicolon or (as of MySQL 8.0.12) comma, optionally followed by space. A given setting cannot use both semicolon and comma separators. 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 final component in the log_error_services value should be a writer. If the final component is a filter, it has no effect because the filtered events are not sent to any writer.

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 enable 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.5.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.


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.