19962017 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. error_logger
error_logger Erlang error logger.

In OTP-21, a new API for logging was added to Erlang/OTP. The old error_logger module can still be used by legacy code, but new code should use the new API instead.

error_logger is no longer started by default, but is automatically started when an event handler is added with error_logger:add_report_handler/1,2. The error_logger module is then also added as a handler to the new logger.

See logger(3) and the Logging chapter in the User's Guide for more information.

The Erlang error logger is an event manager (see OTP Design Principles and gen_event(3)), registered as error_logger.

Error logger is no longer started by default, but is automatically started when an event handler is added with add_report_handler/1,2. The error_logger module is then also added as a handler to the new logger, causing log events to be forwarded from logger to error logger, and consequently to all installed error logger event handlers.

User-defined event handlers can be added to handle application-specific events.

Existing event handlers provided by STDLIB and SASL are still available, but are no longer used by OTP.

Warning events were introduced in Erlang/OTP R9C and are enabled by default as from Erlang/OTP 18.0. To retain backwards compatibility with existing user-defined event handlers, the warning events can be tagged as errors or info using command-line flag ]]>, thus showing up as ERROR REPORT or INFO REPORT in the logs.

 Add an event handler to the error logger.

Adds a new event handler to the error logger. The event handler must be implemented as a gen_event callback module, see gen_event(3).

Handler is typically the name of the callback module and Args is an optional term (defaults to []) passed to the initialization callback function Handler:init/1. The function returns ok if successful.

The event handler must be able to handle the events in this module, see section Events.

 Delete an event handler from the error logger.

Deletes an event handler from the error logger by calling gen_event:delete_handler(error_logger, Handler, []), see gen_event(3).

 Send a standard error event to the error logger.

Sends a standard error event to the error logger. The Format and Data arguments are the same as the arguments of io:format/2 in STDLIB. The event is handled by the standard event handler.

Example:

1> error_logger:error_msg("An error occurred in ~p~n", [a_module]).

=ERROR REPORT==== 11-Aug-2005::14:03:19 ===
An error occurred in a_module
ok

If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged. When in doubt, use error_report/1 instead.

If the Unicode translation modifier (t) is used in the format string, all error handlers must ensure that the formatted output is correctly encoded for the I/O device.

 Send a standard error report event to the error logger.

Sends a standard error report event to the error logger. The event is handled by the standard event handler.

Example:

2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).

=ERROR REPORT==== 11-Aug-2005::13:45:41 ===
    tag1: data1
    a_term
    tag2: data
ok
3> error_logger:error_report("Serious error in my module").

=ERROR REPORT==== 11-Aug-2005::13:45:49 ===
Serious error in my module
ok
 Send a user-defined error report event to the error logger.

Sends a user-defined error report event to the error logger. An event handler to handle the event is supposed to have been added. The event is ignored by the standard event handler.

It is recommended that Report follows the same structure as for error_report/1.

 Get the value of the Kernel application variable error_logger_format_depth.

Returns max(10, Depth), where Depth is the value of error_logger_format_depth in the Kernel application, if Depth is an integer. Otherwise, unlimited is returned.

The error_logger_format_depth variable is deprecated since the logging API was introduced in OTP-21. The variable, and this function, are kept for backwards compatibility since they still might be used by legacy report handlers.

 Send a standard information event to the error logger.

Sends a standard information event to the error logger. The Format and Data arguments are the same as the arguments of io:format/2 in STDLIB. The event is handled by the standard event handler.

Example:

1> error_logger:info_msg("Something happened in ~p~n", [a_module]).

=INFO REPORT==== 11-Aug-2005::14:06:15 ===
Something happened in a_module
ok

If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged. When in doubt, use info_report/1 instead.

If the Unicode translation modifier (t) is used in the format string, all error handlers must ensure that the formatted output is correctly encoded for the I/O device.

 Send a standard information report event to the error logger.

Sends a standard information report event to the error logger. The event is handled by the standard event handler.

Example:

2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).

=INFO REPORT==== 11-Aug-2005::13:55:09 ===
    tag1: data1
    a_term
    tag2: data
ok
3> error_logger:info_report("Something strange happened").

=INFO REPORT==== 11-Aug-2005::13:55:36 ===
Something strange happened
ok
 Send a user-defined information report event to the error logger.

Sends a user-defined information report event to the error logger. An event handler to handle the event is supposed to have been added. The event is ignored by the standard event handler.

It is recommended that Report follows the same structure as for info_report/1.

 Enable or disable error printouts to a file.

Enables or disables printout of standard events to a file.

This is done by adding or deleting the standard event handler for output to file. Thus, calling this function overrides the value of the Kernel error_logger configuration parameter.

Enabling file logging can be used together with calling tty(false), to have a silent system where all standard events are logged to a file only. Only one log file can be active at a time.

Request is one of the following:

{open, Filename}

Opens log file Filename. Returns ok if successful, or {error, allready_have_logfile} if logging to file is already enabled, or an error tuple if another error occurred (for example, if Filename cannot be opened). The file is opened with encoding UTF-8.

 close

Closes the current log file. Returns ok, or {error, module_not_found}.

 filename

Returns the name of the log file Filename, or {error, no_log_file} if logging to file is not enabled.

 Enable or disable printouts to the terminal.

Enables (Flag == true) or disables (Flag == false) printout of standard events to the terminal.

This is done by adding or deleting the standard event handler for output to the terminal. Thus, calling this function overrides the value of the Kernel error_logger configuration parameter.

 Return the current mapping for warning events.

Returns the current mapping for warning events. Events sent using warning_msg/1,2 or warning_report/1,2 are tagged as errors, warnings (default), or info, depending on the value of command-line flag +W.

Example:

os$ erl
Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

Eshell V5.4.8  (abort with ^G)
1> error_logger:warning_map().
warning
2> error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).

=WARNING REPORT==== 11-Aug-2005::15:31:55 ===
Warnings tagged as: warning
ok
3>
User switch command
 --> q
os$ erl +W e
Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]

Eshell V5.4.8  (abort with ^G)
1> error_logger:warning_map().
error
2> error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).

=ERROR REPORT==== 11-Aug-2005::15:31:23 ===
Warnings tagged as: error
ok
 Send a standard warning event to the error logger.

Sends a standard warning event to the error logger. The Format and Data arguments are the same as the arguments of io:format/2 in STDLIB. The event is handled by the standard event handler. It is tagged as an error, warning, or info, see warning_map/0.

If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged. When in doubt, use warning_report/1 instead.

If the Unicode translation modifier (t) is used in the format string, all error handlers must ensure that the formatted output is correctly encoded for the I/O device.

 Send a standard warning report event to the error logger.

Sends a standard warning report event to the error logger. The event is handled by the standard event handler. It is tagged as an error, warning, or info, see warning_map/0.

 Send a user-defined warning report event to the error logger.

Sends a user-defined warning report event to the error logger. An event handler to handle the event is supposed to have been added. The event is ignored by the standard event handler. It is tagged as an error, warning, or info, depending on the value of warning_map/0.
Events

All event handlers added to the error logger must handle the following events. Gleader is the group leader pid of the process that sent the event, and Pid is the process that sent the event.

{error, Gleader, {Pid, Format, Data}}

Generated when error_msg/1,2 or format is called.

 {error_report, Gleader, {Pid, std_error, Report}}

Generated when error_report/1 is called.

 {error_report, Gleader, {Pid, Type, Report}}

Generated when error_report/2 is called.

 {warning_msg, Gleader, {Pid, Format, Data}}

Generated when warning_msg/1,2 is called if warnings are set to be tagged as warnings.

 {warning_report, Gleader, {Pid, std_warning, Report}}

Generated when warning_report/1 is called if warnings are set to be tagged as warnings.

 {warning_report, Gleader, {Pid, Type, Report}}

Generated when warning_report/2 is called if warnings are set to be tagged as warnings.

 {info_msg, Gleader, {Pid, Format, Data}}

Generated when info_msg/1,2 is called.

 {info_report, Gleader, {Pid, std_info, Report}}

Generated when info_report/1 is called.

 {info_report, Gleader, {Pid, Type, Report}}

Generated when info_report/2 is called.

Notice that some system-internal events can also be received. Therefore a catch-all clause last in the definition of the event handler callback function Module:handle_event/2 is necessary. This also applies for Module:handle_info/2, as the event handler must also take care of some system-internal messages.

See Also

gen_event(3), log_mf_h(3) kernel(6) sasl(6)