From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/kernel/doc/src/error_logger.xml | 450 ++++++++++++++++++++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 lib/kernel/doc/src/error_logger.xml (limited to 'lib/kernel/doc/src/error_logger.xml') diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml new file mode 100644 index 0000000000..e107d9b746 --- /dev/null +++ b/lib/kernel/doc/src/error_logger.xml @@ -0,0 +1,450 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + error_logger + + + + +
+ error_logger + Erlang Error Logger + +

The Erlang error logger is an event manager (see + OTP Design Principles and + gen_event(3)), + 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(6).

+

Also the SASL application, if started, adds its own event + handler, which by default writes supervisor-, crash- and progress + reports to tty. See + sasl(6).

+

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(3).

+

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 ]]>, they can instead + be tagged as warnings or info. Tagging them as warnings may + require rewriting existing user defined event handlers.

+ + + + error_msg(Format) -> ok + error_msg(Format, Data) -> ok + format(Format, Data) -> ok + Send an standard error event to the error logger + + Format = string() + Data = [term()] + + +

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
+ +

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 + Send a standard error report event to the error logger + + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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 + Send a user defined error report event to the error logger + + Type = term() + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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 + Return the current mapping for warning events + + 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 + Send a standard warning event to the error logger + + Format = string() + Data = [term()] + + +

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.

+ +

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 + Send a standard warning report event to the error logger + + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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 + Send a user defined warning report event to the error logger + + Type = term() + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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 + Send a standard information event to the error logger + + Format = string() + Data = [term()] + + +

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
+ +

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 + Send a standard information report event to the error logger + + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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 + Send a user defined information report event to the error logger + + Type = term() + Report = [{Tag, Data} | term()] | string() | term() +  Tag = Data = term() + + +

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) -> Result + add_report_handler(Handler, Args) -> Result + Add an event handler to the error logger + + Handler, Args, Result -- see gen_event:add_handler/3 + + +

Adds a new event handler to the error logger. The event + handler must be implemented as a gen_event callback + module, see + gen_event(3).

+

Handler is typically the name of the callback module + and Args is an optional term (defaults to []) passed + to the initialization callback function Module: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 + Delete an event handler from the error logger + + Handler, Result -- see gen_event:delete_handler/3 + + +

Deletes an event handler from the error logger by calling + gen_event:delete_handler(error_logger, Handler, []), + see gen_event(3).

+ + + + tty(Flag) -> ok + Enable or disable printouts to the tty + + Flag = bool() + + +

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) -> ok | Filename | {error, What} + Enable or disable error printouts to a file + + Request = {open, Filename} | close | filename +  Filename = atom() | string() + What = allready_have_logfile | no_log_file | term() + + +

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, What}.

+ + 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(3), log_mf_h(3), kernel(6), sasl(6)

+
+ + -- cgit v1.2.3