error_logger

MODULE

error_logger

MODULE SUMMARY

Erlang Error Logger

DESCRIPTION

The Erlang error logger is an event manager (see
OTP Design Principles and
gen_event(3)),
registered as error_logger. Error, warning and info events
are sent to the error logger from the Erlang runtime system and
the different Erlang/OTP applications. The events are, by default,
logged to tty. Note that an event from a process P is
logged at the node of the group leader of P. This means
that log output is directed to the node from which a process was
created, which not necessarily is the same node as where it is
executing.

Initially, error_logger only has a primitive event
handler, which buffers and prints the raw event messages. During
system startup, the application Kernel replaces this with a
standard event handler, by default one which writes
nicely formatted output to tty. Kernel can also be configured so
that events are logged to file instead, or not logged at all, see
kernel(6).

Also the SASL application, if started, adds its own event
handler, which by default writes supervisor-, crash- and progress
reports to tty. See
sasl(6).

It is recommended that user defined applications should report
errors through the error logger, in order to get uniform reports.
User defined event handlers can be added to handle application
specific events. (add_report_handler/1,2). Also, there is
a useful event handler in STDLIB for multi-file logging of events,
see log_mf_h(3).

Warning events was introduced in Erlang/OTP R9C. To retain
backwards compatibility, these are by default tagged as errors,
thus showing up as error reports in the logs. By using
the command line flag +W <w | i>, they can instead
be tagged as warnings or info. Tagging them as warnings may
require rewriting existing user defined event handlers.

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

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

Warning

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.

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 either as an error, warning or info,
depending on the value of
warning_map/0.

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 in combination with calling
tty(false), in order to have a silent system, where
all standard events are logged to a file only.
There can only be one active log file at a time.

Request is one of:

{open, Filename}

Opens the 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
could not be opened.

close

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

filename

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

All event handlers added to the error logger must handle
the following events. Gleader is the group leader pid of
the process which sent the event, and Pid is the process
which 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, provided
that warnings are set to be tagged as warnings.

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

Generated when warning_report/1 is called, provided
that warnings are set to be tagged as warnings.

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

Generated when warning_report/2 is called, provided
that 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.

Note that also a number of system internal events may be
received, a catch-all clause last in the definition of
the event handler callback function Module:handle_event/2
is necessary. This also holds true for
Module:handle_info/2, as there are a number of system
internal messages the event handler must take care of as well.