error_logger(3erl) Erlang Module Definition error_logger(3erl)
NAME
error_logger - Erlang error logger.
DESCRIPTION
Note:
In Erlang/OTP 21.0, a new API for logging was added. The old error_log-
ger module can still be used by legacy code, but log events are redi-
rected to the new Logger API. New code should use the Logger API di-
rectly.
error_logger is no longer started by default, but is automatically
started when an event handler is added with error_logger:add_re-
port_handler/1,2. The error_logger module is then also added as a han-
dler to the new logger.
See logger(3erl) 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(3erl)), 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 avail-
able, but are no longer used by OTP.
Warning events were introduced in Erlang/OTP R9C and are enabled by de-
fault 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 +W <e | i | w>, thus showing
up as ERROR REPORT or INFO REPORT in the logs.
DATA TYPES
report() =
[{Tag :: term(), Data :: term()} | term()] | string() | term()
EXPORTS
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 in this mod-
ule, see section Events.
The first time this function is called, error_logger is added as
a Logger handler, and the error_logger process is started.
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).
If no more event handlers exist after the deletion, error_logger
is removed as a Logger handler, and the error_logger process is
stopped.
error_msg(Format) -> ok
error_msg(Format, Data) -> ok
format(Format, Data) -> ok
Types:
Format = string()
Data = list()
Log a standard error event. The Format and Data arguments are
the same as the arguments of io:format/2 in STDLIB.
Error logger forwards the event to Logger, including metadata
that allows backwards compatibility with legacy error logger
event handlers.
The event is handled by the default Logger handler.
These functions are kept for backwards compatibility and must
not be used by new code. Use the ?LOG_ERROR macro or logger:er-
ror/1,2,3 instead.
Example:
1> error_logger:error_msg("An error occurred in ~p", [a_module]).
=ERROR REPORT==== 22-May-2018::11:18:43.376917 ===
An error occurred in a_module
ok
Warning:
If the Unicode translation modifier (t) is used in the format
string, all event handlers must ensure that the formatted output
is correctly encoded for the I/O device.
error_report(Report) -> ok
Types:
Report = report()
Log a standard error event. Error logger forwards the event to
Logger, including metadata that allows backwards compatibility
with legacy error logger event handlers.
The event is handled by the default Logger handler.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_ERROR macro or logger:er-
ror/1,2,3 instead.
Example:
2> error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).
=ERROR REPORT==== 22-May-2018::11:24:23.699306 ===
tag1: data1
a_term
tag2: data
ok
3> error_logger:error_report("Serious error in my module").
=ERROR REPORT==== 22-May-2018::11:24:45.972445 ===
Serious error in my module
ok
error_report(Type, Report) -> ok
Types:
Type = term()
Report = report()
Log a user-defined error event. Error logger forwards the event
to Logger, including metadata that allows backwards compatibil-
ity with legacy error logger event handlers.
Error logger also adds a domain field with value [Type] to this
event's metadata, causing the filters of the default Logger han-
dler to discard the event. A different Logger handler, or an er-
ror logger event handler, must be added to handle this event.
It is recommended that Report follows the same structure as for
error_report/1.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_ERROR macro or logger:er-
ror/1,2,3 instead.
get_format_depth() -> unlimited | integer() >= 1
Returns max(10, Depth), where Depth is the value of error_log-
ger_format_depth in the Kernel application, if Depth is an inte-
ger. Otherwise, unlimited is returned.
Note:
The error_logger_format_depth variable is deprecated since the
Logger API was introduced in Erlang/OTP 21.0. The variable, and
this function, are kept for backwards compatibility since they
still might be used by legacy report handlers.
info_msg(Format) -> ok
info_msg(Format, Data) -> ok
Types:
Format = string()
Data = list()
Log a standard information event. The Format and Data arguments
are the same as the arguments of io:format/2 in STDLIB.
Error logger forwards the event to Logger, including metadata
that allows backwards compatibility with legacy error logger
event handlers.
The event is handled by the default Logger handler.
These functions are kept for backwards compatibility and must
not be used by new code. Use the ?LOG_INFO macro or log-
ger:info/1,2,3 instead.
Example:
1> error_logger:info_msg("Something happened in ~p", [a_module]).
=INFO REPORT==== 22-May-2018::12:03:32.612462 ===
Something happened in a_module
ok
Warning:
If the Unicode translation modifier (t) is used in the format
string, all event handlers must ensure that the formatted output
is correctly encoded for the I/O device.
info_report(Report) -> ok
Types:
Report = report()
Log a standard information event. Error logger forwards the
event to Logger, including metadata that allows backwards com-
patibility with legacy error logger event handlers.
The event is handled by the default Logger handler.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_INFO macro or log-
ger:info/1,2,3 instead.
Example:
2> error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).
=INFO REPORT==== 22-May-2018::12:06:35.994440 ===
tag1: data1
a_term
tag2: data
ok
3> error_logger:info_report("Something strange happened").
=INFO REPORT==== 22-May-2018::12:06:49.066872 ===
Something strange happened
ok
info_report(Type, Report) -> ok
Types:
Type = any()
Report = report()
Log a user-defined information event. Error logger forwards the
event to Logger, including metadata that allows backwards com-
patibility with legacy error logger event handlers.
Error logger also adds a domain field with value [Type] to this
event's metadata, causing the filters of the default Logger han-
dler to discard the event. A different Logger handler, or an er-
ror logger event handler, must be added to handle this event.
It is recommended that Report follows the same structure as for
info_report/1.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_INFO macro or log-
ger:info/1,2,3 instead.
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 error_logger_file_h event
handler, and thus indirectly adding error_logger as a Logger
handler.
Notice that this function does not manipulate the Logger config-
uration directly, meaning that if the default Logger handler is
already logging to a file, this function can potentially cause
logging to a second file.
This function is useful as a shortcut during development and
testing, but must not be used in a production system. See sec-
tion Logging in the Kernel User's Guide, and the logger(3erl)
manual page for information about how to configure Logger for
live systems.
Request is one of the following:
{open, Filename}:
Opens log file Filename. Returns ok if successful, or {er-
ror, 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, mod-
ule_not_found}.
filename:
Returns the name of the log file Filename, or {error,
no_log_file} if logging to file is not enabled.
tty(Flag) -> ok
Types:
Flag = boolean()
Enables (Flag == true) or disables (Flag == false) printout of
standard events to the terminal.
This is done by manipulating the Logger configuration. The func-
tion is useful as a shortcut during development and testing, but
must not be used in a production system. See section Logging in
the Kernel User's Guide, and the logger(3erl) manual page for
information about how to configure Logger for live systems.
warning_map() -> Tag
Types:
Tag = error | warning | info
Returns the current mapping for warning events. Events sent us-
ing 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
warning_msg(Format) -> ok
warning_msg(Format, Data) -> ok
Types:
Format = string()
Data = list()
Log a standard warning event. The Format and Data arguments are
the same as the arguments of io:format/2 in STDLIB.
Error logger forwards the event to Logger, including metadata
that allows backwards compatibility with legacy error logger
event handlers.
The event is handled by the default Logger handler. The log
level can be changed to error or info, see warning_map/0.
These functions are kept for backwards compatibility and must
not be used by new code. Use the ?LOG_WARNING macro or log-
ger:warning/1,2,3 instead.
Warning:
If the Unicode translation modifier (t) is used in the format
string, all event handlers must ensure that the formatted output
is correctly encoded for the I/O device.
warning_report(Report) -> ok
Types:
Report = report()
Log a standard warning event. Error logger forwards the event to
Logger, including metadata that allows backwards compatibility
with legacy error logger event handlers.
The event is handled by the default Logger handler. The log
level can be changed to error or info, see warning_map/0.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_WARNING macro or logger:warn-
ing/1,2,3 instead.
warning_report(Type, Report) -> ok
Types:
Type = any()
Report = report()
Log a user-defined warning event. Error logger forwards the
event to Logger, including metadata that allows backwards com-
patibility with legacy error logger event handlers.
Error logger also adds a domain field with value [Type] to this
event's metadata, causing the filters of the default Logger han-
dler to discard the event. A different Logger handler, or an er-
ror logger event handler, must be added to handle this event.
The log level can be changed to error or info, see warn-
ing_map/0.
It is recommended that Report follows the same structure as for
warning_report/1.
This functions is kept for backwards compatibility and must not
be used by new code. Use the ?LOG_WARNING macro or logger:warn-
ing/1,2,3 instead.
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 Mod-
ule:handle_info/2, as the event handler must also take care of some
system-internal messages.
SEE ALSO
gen_event(3erl), logger(3erl), log_mf_h(3erl), kernel(7), sasl(7)
Ericsson AB kernel 7.0 error_logger(3erl)