.TH error_logger 3erl "kernel 7.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
error_logger \- Erlang error logger.
.SH DESCRIPTION
.LP

.RS -4
.B
Note:
.RE
In Erlang/OTP 21\&.0, a new API for logging was added\&. The old \fIerror_logger\fR\& module can still be used by legacy code, but log events are redirected to the new Logger API\&. New code should use the Logger API directly\&.
.LP
\fIerror_logger\fR\& is no longer started by default, but is automatically started when an event handler is added with \fIerror_logger:add_report_handler/1,2\fR\&\&. The \fIerror_logger\fR\& module is then also added as a handler to the new logger\&.
.LP
See \fIlogger(3erl)\fR\& and the Logging chapter in the User\&'s Guide for more information\&.

.LP
The Erlang \fIerror logger\fR\& is an event manager (see OTP Design Principles and \fIgen_event(3erl)\fR\&), registered as \fIerror_logger\fR\&\&.
.LP
Error logger is no longer started by default, but is automatically started when an event handler is added with \fIadd_report_handler/1,2\fR\&\&. The \fIerror_logger\fR\& 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\&.
.LP
User-defined event handlers can be added to handle application-specific events\&.
.LP
Existing event handlers provided by STDLIB and SASL are still available, but are no longer used by OTP\&.
.LP
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 \fIerrors\fR\& or \fIinfo\fR\& using command-line flag \fI+W <e | i | w>\fR\&, thus showing up as \fIERROR REPORT\fR\& or \fIINFO REPORT\fR\& in the logs\&.
.SH DATA TYPES
.nf

\fBreport()\fR\& = 
.br
    [{Tag :: term(), Data :: term()} | term()] | string() | term()
.br
.fi
.SH EXPORTS
.LP
.nf

.B
add_report_handler(Handler) -> any()
.br
.fi
.br
.nf

.B
add_report_handler(Handler, Args) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Handler = module()
.br
Args = gen_event:handler_args()
.br
Result = gen_event:add_handler_ret()
.br
.RE
.RE
.RS
.LP
Adds a new event handler to the error logger\&. The event handler must be implemented as a \fIgen_event\fR\& callback module, see \fIgen_event(3erl)\fR\&\&.
.LP
\fIHandler\fR\& is typically the name of the callback module and \fIArgs\fR\& is an optional term (defaults to []) passed to the initialization callback function \fIHandler:init/1\fR\&\&. The function returns \fIok\fR\& if successful\&.
.LP
The event handler must be able to handle the events in this module, see section Events\&.
.LP
The first time this function is called, \fIerror_logger\fR\& is added as a Logger handler, and the \fIerror_logger\fR\& process is started\&.
.RE

.LP
.nf

.B
delete_report_handler(Handler) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Handler = module()
.br
Result = gen_event:del_handler_ret()
.br
.RE
.RE
.RS
.LP
Deletes an event handler from the error logger by calling \fIgen_event:delete_handler(error_logger, Handler, [])\fR\&, see \fIgen_event(3erl)\fR\&\&.
.LP
If no more event handlers exist after the deletion, \fIerror_logger\fR\& is removed as a Logger handler, and the \fIerror_logger\fR\& process is stopped\&.
.RE

.LP
.nf

.B
error_msg(Format) -> ok
.br
.fi
.br
.nf

.B
error_msg(Format, Data) -> ok
.br
.fi
.br
.nf

.B
format(Format, Data) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Format = string()
.br
Data = list()
.br
.RE
.RE
.RS
.LP
Log a standard error event\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\& in STDLIB\&.
.LP
Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&.
.LP
These functions are kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_ERROR\fR\& macro or \fIlogger:error/1,2,3\fR\& instead\&.
.LP
\fIExample:\fR\&
.LP
.nf

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
.fi
.LP

.RS -4
.B
Warning:
.RE
If the Unicode translation modifier (\fIt\fR\&) is used in the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device\&.

.RE

.LP
.nf

.B
error_report(Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Report = report()
.br
.RE
.RE
.RS
.LP
Log a standard error event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_ERROR\fR\& macro or \fIlogger:error/1,2,3\fR\& instead\&.
.LP
\fIExample:\fR\&
.LP
.nf

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
.fi
.RE

.LP
.nf

.B
error_report(Type, Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = term()
.br
Report = report()
.br
.RE
.RE
.RS
.LP
Log a user-defined error event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
Error logger also adds a \fIdomain\fR\& field with value \fI[Type]\fR\& to this event\&'s metadata, causing the filters of the default Logger handler to discard the event\&. A different Logger handler, or an error logger event handler, must be added to handle this event\&.
.LP
It is recommended that \fIReport\fR\& follows the same structure as for \fIerror_report/1\fR\&\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_ERROR\fR\& macro or \fIlogger:error/1,2,3\fR\& instead\&.
.RE

.LP
.nf

.B
get_format_depth() -> unlimited | integer() >= 1
.br
.fi
.br
.RS
.LP
Returns \fImax(10, Depth)\fR\&, where \fIDepth\fR\& is the value of \fIerror_logger_format_depth\fR\& in the Kernel application, if Depth is an integer\&. Otherwise, \fIunlimited\fR\& is returned\&.
.LP

.RS -4
.B
Note:
.RE
The \fIerror_logger_format_depth\fR\& 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\&.

.RE

.LP
.nf

.B
info_msg(Format) -> ok
.br
.fi
.br
.nf

.B
info_msg(Format, Data) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Format = string()
.br
Data = list()
.br
.RE
.RE
.RS
.LP
Log a standard information event\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\& in STDLIB\&.
.LP
Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&.
.LP
These functions are kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_INFO\fR\& macro or \fIlogger:info/1,2,3\fR\& instead\&.
.LP
\fIExample:\fR\&
.LP
.nf

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
.fi
.LP

.RS -4
.B
Warning:
.RE
If the Unicode translation modifier (\fIt\fR\&) is used in the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device\&.

.RE

.LP
.nf

.B
info_report(Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Report = report()
.br
.RE
.RE
.RS
.LP
Log a standard information event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_INFO\fR\& macro or \fIlogger:info/1,2,3\fR\& instead\&.
.LP
\fIExample:\fR\&
.LP
.nf

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
.fi
.RE

.LP
.nf

.B
info_report(Type, Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = any()
.br
Report = report()
.br
.RE
.RE
.RS
.LP
Log a user-defined information event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
Error logger also adds a \fIdomain\fR\& field with value \fI[Type]\fR\& to this event\&'s metadata, causing the filters of the default Logger handler to discard the event\&. A different Logger handler, or an error logger event handler, must be added to handle this event\&.
.LP
It is recommended that \fIReport\fR\& follows the same structure as for \fIinfo_report/1\fR\&\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_INFO\fR\& macro or \fIlogger:info/1,2,3\fR\& instead\&.
.RE

.LP
.nf

.B
logfile(Request :: {open, Filename}) -> ok | {error, OpenReason}
.br
.fi
.br
.nf

.B
logfile(Request :: close) -> ok | {error, CloseReason}
.br
.fi
.br
.nf

.B
logfile(Request :: filename) -> Filename | {error, FilenameReason}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = file:name()
.br
OpenReason = allready_have_logfile | open_error()
.br
CloseReason = module_not_found
.br
FilenameReason = no_log_file
.br
.nf
\fBopen_error()\fR\& = file:posix() | badarg | system_limit
.fi
.br
.RE
.RE
.RS
.LP
Enables or disables printout of standard events to a file\&.
.LP
This is done by adding or deleting the \fIerror_logger_file_h\fR\& event handler, and thus indirectly adding \fIerror_logger\fR\& as a Logger handler\&.
.LP
Notice that this function does not manipulate the Logger configuration directly, meaning that if the default Logger handler is already logging to a file, this function can potentially cause logging to a second file\&.
.LP
This function 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 \fIlogger(3erl)\fR\& manual page for information about how to configure Logger for live systems\&.
.LP
\fIRequest\fR\& is one of the following:
.RS 2
.TP 2
.B
\fI{open, Filename}\fR\&:
Opens log file \fIFilename\fR\&\&. Returns \fIok\fR\& if successful, or \fI{error, allready_have_logfile}\fR\& if logging to file is already enabled, or an error tuple if another error occurred (for example, if \fIFilename\fR\& cannot be opened)\&. The file is opened with encoding UTF-8\&.
.TP 2
.B
\fIclose\fR\&:
Closes the current log file\&. Returns \fIok\fR\&, or \fI{error, module_not_found}\fR\&\&.
.TP 2
.B
\fIfilename\fR\&:
Returns the name of the log file \fIFilename\fR\&, or \fI{error, no_log_file}\fR\& if logging to file is not enabled\&.
.RE
.RE

.LP
.nf

.B
tty(Flag) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Flag = boolean()
.br
.RE
.RE
.RS
.LP
Enables (\fIFlag == true\fR\&) or disables (\fIFlag == false\fR\&) printout of standard events to the terminal\&.
.LP
This is done by manipulating the Logger configuration\&. The function 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 \fIlogger(3erl)\fR\& manual page for information about how to configure Logger for live systems\&.
.RE

.LP
.nf

.B
warning_map() -> Tag
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Tag = error | warning | info
.br
.RE
.RE
.RS
.LP
Returns the current mapping for warning events\&. Events sent using \fIwarning_msg/1,2\fR\& or \fIwarning_report/1,2\fR\& are tagged as errors, warnings (default), or info, depending on the value of command-line flag \fI+W\fR\&\&.
.LP
\fIExample:\fR\&
.LP
.nf

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
.fi
.RE

.LP
.nf

.B
warning_msg(Format) -> ok
.br
.fi
.br
.nf

.B
warning_msg(Format, Data) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Format = string()
.br
Data = list()
.br
.RE
.RE
.RS
.LP
Log a standard warning event\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\& in STDLIB\&.
.LP
Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&. The log level can be changed to error or info, see \fIwarning_map/0\fR\&\&.
.LP
These functions are kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_WARNING\fR\& macro or \fIlogger:warning/1,2,3\fR\& instead\&.
.LP

.RS -4
.B
Warning:
.RE
If the Unicode translation modifier (\fIt\fR\&) is used in the format string, all event handlers must ensure that the formatted output is correctly encoded for the I/O device\&.

.RE

.LP
.nf

.B
warning_report(Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Report = report()
.br
.RE
.RE
.RS
.LP
Log a standard warning event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
The event is handled by the default Logger handler\&. The log level can be changed to error or info, see \fIwarning_map/0\fR\&\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_WARNING\fR\& macro or \fIlogger:warning/1,2,3\fR\& instead\&.
.RE

.LP
.nf

.B
warning_report(Type, Report) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Type = any()
.br
Report = report()
.br
.RE
.RE
.RS
.LP
Log a user-defined warning event\&. Error logger forwards the event to Logger, including metadata that allows backwards compatibility with legacy error logger event handlers\&.
.LP
Error logger also adds a \fIdomain\fR\& field with value \fI[Type]\fR\& to this event\&'s metadata, causing the filters of the default Logger handler to discard the event\&. A different Logger handler, or an error logger event handler, must be added to handle this event\&.
.LP
The log level can be changed to error or info, see \fIwarning_map/0\fR\&\&.
.LP
It is recommended that \fIReport\fR\& follows the same structure as for \fIwarning_report/1\fR\&\&.
.LP
This functions is kept for backwards compatibility and must not be used by new code\&. Use the \fI?LOG_WARNING\fR\& macro or \fIlogger:warning/1,2,3\fR\& instead\&.
.RE

.SH "EVENTS"

.LP
All event handlers added to the error logger must handle the following events\&. \fIGleader\fR\& is the group leader pid of the process that sent the event, and \fIPid\fR\& is the process that sent the event\&.
.RS 2
.TP 2
.B
\fI{error, Gleader, {Pid, Format, Data}}\fR\&:
Generated when \fIerror_msg/1,2\fR\& or \fIformat\fR\& is called\&.
.TP 2
.B
\fI{error_report, Gleader, {Pid, std_error, Report}}\fR\&:
Generated when \fIerror_report/1\fR\& is called\&.
.TP 2
.B
\fI{error_report, Gleader, {Pid, Type, Report}}\fR\&:
Generated when \fIerror_report/2\fR\& is called\&.
.TP 2
.B
\fI{warning_msg, Gleader, {Pid, Format, Data}}\fR\&:
Generated when \fIwarning_msg/1,2\fR\& is called if warnings are set to be tagged as warnings\&.
.TP 2
.B
\fI{warning_report, Gleader, {Pid, std_warning, Report}}\fR\&:
Generated when \fIwarning_report/1\fR\& is called if warnings are set to be tagged as warnings\&.
.TP 2
.B
\fI{warning_report, Gleader, {Pid, Type, Report}}\fR\&:
Generated when \fIwarning_report/2\fR\& is called if warnings are set to be tagged as warnings\&.
.TP 2
.B
\fI{info_msg, Gleader, {Pid, Format, Data}}\fR\&:
Generated when \fIinfo_msg/1,2\fR\& is called\&.
.TP 2
.B
\fI{info_report, Gleader, {Pid, std_info, Report}}\fR\&:
Generated when \fIinfo_report/1\fR\& is called\&.
.TP 2
.B
\fI{info_report, Gleader, {Pid, Type, Report}}\fR\&:
Generated when \fIinfo_report/2\fR\& is called\&.
.RE
.LP
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 \fIModule:handle_event/2\fR\& is necessary\&. This also applies for \fIModule:handle_info/2\fR\&, as the event handler must also take care of some system-internal messages\&.
.SH "SEE ALSO"

.LP
\fIgen_event(3erl)\fR\&, \fIlogger(3erl)\fR\&, \fIlog_mf_h(3erl)\fR\&, \fIkernel(7)\fR\&, \fIsasl(7)\fR\&