.TH error_logger 3erl "kernel 5.1.1" "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 \fB\fIgen_event(3erl)\fR\&\fR\&), registered as \fIerror_logger\fR\&\&. Errors, warnings, 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 the terminal\&. Notice 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\& has only a primitive event handler, which buffers and prints the raw event messages\&. During system startup, the Kernel application replaces this with a \fIstandard event handler\fR\&, by default one that writes nicely formatted output to the terminal\&. Kernel can also be configured so that events are logged to a file instead, or not logged at all, see \fB\fIkernel(7)\fR\&\fR\&\&. .LP Also the SASL application, if started, adds its own event handler, which by default writes supervisor, crash, and progress reports to the terminal\&. See \fB\fIsasl(7)\fR\&\fR\&\&. .LP It is recommended that user-defined applications report errors through the error logger to get uniform reports\&. User-defined event handlers can be added to handle application-specific events, see \fB\fIadd_report_handler/1,2\fR\&\fR\&\&. Also, a useful event handler is provided in STDLIB for multi-file logging of events, see \fB\fIlog_mf_h(3erl)\fR\&\fR\&\&. .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 \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 = \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 \fB\fIgen_event(3erl)\fR\&\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 \fBEvents\fR\&\&. .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 \fB\fIgen_event(3erl)\fR\&\fR\&\&. .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 Sends a standard error event to the error logger\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fB\fIio:format/2\fR\&\fR\& in STDLIB\&. The event is handled by the standard event handler\&. .LP \fIExample:\fR\& .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 \fB\fIerror_report/1\fR\&\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 \fIExample:\fR\& .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 \fB\fIerror_report/1\fR\&\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 \fB\fIio:format/2\fR\&\fR\& in STDLIB\&. The event is handled by the standard event handler\&. .LP \fIExample:\fR\& .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 \fIExample:\fR\& .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 \fB\fIinfo_report/1\fR\&\fR\&\&. .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 together with calling \fItty(false)\fR\&, to have a silent system where all standard events are logged to a file only\&. Only one log file can be active at a time\&. .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)\&. .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 adding or deleting the standard event handler for output to the terminal\&. Thus, calling this function overrides the value of the Kernel \fIerror_logger\fR\& configuration parameter\&. .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 Sends a standard warning event to the error logger\&. The \fIFormat\fR\& and \fIData\fR\& arguments are the same as the arguments of \fB\fIio:format/2\fR\&\fR\& in STDLIB\&. The event is handled by the standard event handler\&. It is tagged as an error, warning, or info, see \fB\fIwarning_map/0\fR\&\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 as an error, warning, or info, see \fB\fIwarning_map/0\fR\&\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 as an error, warning, or info, depending on the value of \fB\fIwarning_map/0\fR\&\fR\&\&. .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 \fB\fIgen_event(3erl)\fR\&\fR\&, \fB\fIlog_mf_h(3erl)\fR\&\fR\& \fB\fIkernel(7)\fR\&\fR\& \fB\fIsasl(7)\fR\&\fR\&