.TH error_logger 3erl "kernel 3.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
error_logger \- Erlang Error Logger
.SH DESCRIPTION
.LP
The Erlang \fIerror logger\fR\& is an event manager (see \fBOTP Design Principles\fR\& and \fBgen_event(3erl)\fR\&), registered as \fIerror_logger\fR\&\&. 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 \fIP\fR\& is logged at the node of the group leader of \fIP\fR\&\&. 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\&.
.LP
Initially, \fIerror_logger\fR\& only has a primitive event handler, which buffers and prints the raw event messages\&. During system startup, the application Kernel replaces this with a \fIstandard event handler\fR\&, 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 \fBkernel(7)\fR\&\&.
.LP
Also the SASL application, if started, adds its own event handler, which by default writes supervisor, crash and progress reports to tty\&. See \fBsasl(7)\fR\&\&.
.LP
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\&. (\fIadd_report_handler/1,2\fR\&)\&. Also, there is a useful event handler in STDLIB for multi-file logging of events, see \fIlog_mf_h(3erl)\fR\&\&.
.LP
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 \fI+W <w | i>\fR\&, they can instead be tagged as warnings or info\&. Tagging them as warnings may require rewriting existing user defined event handlers\&.
.SH DATA TYPES
.nf

\fBreport()\fR\& = [{Tag :: term(), Data :: term()} | term()]
.br
         | string()
.br
         | term()
.br
.fi
.SH EXPORTS
.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
Sends a standard error event to the error logger\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\&\&. The event is handled by the standard event handler\&.
.LP
.nf

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

.RS -4
.B
Warning:
.RE
If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged\&. When in doubt, use \fIerror_report/1\fR\& instead\&.

.RE

.LP
.nf

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

.RS 3
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
Sends a standard error report event to the error logger\&. The event is handled by the standard event handler\&.
.LP
.nf

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

.LP
.nf

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

.RS 3
Type = term()
.br
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
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\&.
.LP
It is recommended that \fIReport\fR\& follows the same structure as for \fIerror_report/1\fR\&\&.
.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 (default), warnings or info, depending on the value of the command line flag \fI+W\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()\&.
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
.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
Sends a standard warning event to the error logger\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\&\&. The event is handled by the standard event handler\&. It is tagged either as an error, warning or info, see \fBwarning_map/0\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged\&. When in doubt, use \fIwarning_report/1\fR\& instead\&.

.RE

.LP
.nf

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

.RS 3
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
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 \fBwarning_map/0\fR\&\&.
.RE

.LP
.nf

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

.RS 3
Type = any()
.br
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
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 \fBwarning_map/0\fR\&\&.
.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
Sends a standard information event to the error logger\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fIio:format/2\fR\&\&. The event is handled by the standard event handler\&.
.LP
.nf

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

.RS -4
.B
Warning:
.RE
If called with bad arguments, this function can crash the standard event handler, meaning no further events are logged\&. When in doubt, use \fIinfo_report/1\fR\& instead\&.

.RE

.LP
.nf

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

.RS 3
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
Sends a standard information report event to the error logger\&. The event is handled by the standard event handler\&.
.LP
.nf

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

.LP
.nf

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

.RS 3
Type = any()
.br
Report = \fBreport()\fR\&
.br
.RE
.RE
.RS
.LP
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\&.
.LP
It is recommended that \fIReport\fR\& follows the same structure as for \fIinfo_report/1\fR\&\&.
.RE

.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 = \fBgen_event:handler_args()\fR\&
.br
Result = \fBgen_event:add_handler_ret()\fR\&
.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 \fBgen_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 \fBevents\fR\& described below\&.
.RE

.LP
.nf

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

.RS 3
Handler = module()
.br
Result = \fBgen_event:del_handler_ret()\fR\&
.br
.RE
.RE
.RS
.LP
Deletes an event handler from the error logger by calling \fIgen_event:delete_handler(error_logger, Handler, [])\fR\&, see \fBgen_event(3erl)\fR\&\&.
.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 tty\&.
.LP
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 \fIerror_logger\fR\& configuration parameter\&.
.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 = \fBfile:name()\fR\&
.br
OpenReason = allready_have_logfile | \fBopen_error()\fR\&
.br
CloseReason = module_not_found
.br
FilenameReason = no_log_file
.br
.nf
\fBopen_error()\fR\& = \fBfile:posix()\fR\& | 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 standard event handler for output to file, thus calling this function overrides the value of the Kernel \fIerror_logger\fR\& configuration parameter\&.
.LP
Enabling file logging can be used in combination with calling \fItty(false)\fR\&, 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\&.
.LP
\fIRequest\fR\& is one of:
.RS 2
.TP 2
.B
\fI{open, Filename}\fR\&:
Opens the 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\& could not be opened\&.
.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

.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 which sent the event, and \fIPid\fR\& is the process which 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, provided that 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, provided that 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, provided that 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
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 \fIModule:handle_event/2\fR\& is necessary\&. This also holds true for \fIModule:handle_info/2\fR\&, as there are a number of system internal messages the event handler must take care of as well\&.
.SH "SEE ALSO"

.LP
gen_event(3erl), log_mf_h(3erl), kernel(7), sasl(7)