Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
error_logger - Erlang Error Logger
DESCRIPTION
The Erlang error logger is an event manager (see OTP Design Principles and
gen_event(3erl)), 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(7).
Also the SASL application, if started, adds its own event handler, which by default writes
supervisor, crash and progress reports to tty. See sasl(7).
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(3erl).
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.
DATA TYPES
report() = [{Tag :: term(), Data :: term()} | term()]
| string()
| term()
EXPORTS
error_msg(Format) -> ok
error_msg(Format, Data) -> ok
format(Format, Data) -> ok
Types:
Format = string()
Data = list()
Sends a standard error 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.
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
Warning:
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.
error_report(Report) -> ok
Types:
Report = report()
Sends a standard error report event to the error logger. The event is handled by
the standard event handler.
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
error_report(Type, Report) -> ok
Types:
Type = term()
Report = report()
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.
warning_map() -> Tag
Types:
Tag = error | warning | info
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.
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().
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
3>
User switch command
--> q
os$ erl +W w
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
warning_msg(Format) -> ok
warning_msg(Format, Data) -> ok
Types:
Format = string()
Data = list()
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.
warning_report(Report) -> ok
Types:
Report = report()
Sends a standard warning report event to the error logger. The event is handled by
the standard event handler. It is tagged either as an error, warning or info, see
warning_map/0.
warning_report(Type, Report) -> ok
Types:
Type = any()
Report = report()
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.
info_msg(Format) -> ok
info_msg(Format, Data) -> ok
Types:
Format = string()
Data = list()
Sends a standard information 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.
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
Warning:
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.
info_report(Report) -> ok
Types:
Report = report()
Sends a standard information report event to the error logger. The event is handled
by the standard event handler.
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
info_report(Type, Report) -> ok
Types:
Type = any()
Report = report()
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.
add_report_handler(Handler) -> any()
add_report_handler(Handler, Args) -> Result
Types:
Handler = module()
Args = gen_event:handler_args()
Result = gen_event:add_handler_ret()
Adds a new event handler to the error logger. The event handler must be implemented
as a gen_event callback module, see gen_event(3erl).
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 described below.
delete_report_handler(Handler) -> Result
Types:
Handler = module()
Result = gen_event:del_handler_ret()
Deletes an event handler from the error logger by calling
gen_event:delete_handler(error_logger, Handler, []), see gen_event(3erl).
tty(Flag) -> ok
Types:
Flag = boolean()
Enables (Flag == true) or disables (Flag == false) printout of standard events to
the tty.
This is done by adding or deleting the standard event handler for output to tty,
thus calling this function overrides the value of the Kernel error_logger
configuration parameter.
logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}
logfile(Request :: close) -> ok | {error, CloseReason}
logfile(Request :: filename) -> Filename | {error, FilenameReason}
Types:
Filename = file:name()
OpenReason = allready_have_logfile | open_error()
CloseReason = module_not_found
FilenameReason = no_log_file
open_error() = file:posix() | badarg | system_limit
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 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, module_not_found}.
filename:
Returns the name of the log file Filename, or {error, no_log_file} if logging
to file is not enabled.
EVENTS
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.
SEE ALSO
gen_event(3erl), log_mf_h(3erl), kernel(7), sasl(7)