diff options
Diffstat (limited to 'lib/kernel/doc/src/error_logger.xml')
| -rw-r--r-- | lib/kernel/doc/src/error_logger.xml | 450 |
1 files changed, 450 insertions, 0 deletions
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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1996</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>error_logger</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>error_logger</module> + <modulesummary>Erlang Error Logger</modulesummary> + <description> + <p>The Erlang <em>error logger</em> is an event manager (see + <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso> and + <seealso marker="stdlib:gen_event">gen_event(3)</seealso>), + registered as <c>error_logger</c>. 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 <c>P</c> is + logged at the node of the group leader of <c>P</c>. 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.</p> + <p>Initially, <c>error_logger</c> only has a primitive event + handler, which buffers and prints the raw event messages. During + system startup, the application Kernel replaces this with a + <em>standard event handler</em>, 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 + <seealso marker="kernel_app">kernel(6)</seealso>.</p> + <p>Also the SASL application, if started, adds its own event + handler, which by default writes supervisor-, crash- and progress + reports to tty. See + <seealso marker="sasl:sasl_app">sasl(6)</seealso>.</p> + <p>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. (<c>add_report_handler/1,2</c>). Also, there is + a useful event handler in STDLIB for multi-file logging of events, + see <c>log_mf_h(3)</c>.</p> + <p>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 <c><![CDATA[+W <w | i>]]></c>, they can instead + be tagged as warnings or info. Tagging them as warnings may + require rewriting existing user defined event handlers.</p> + </description> + <funcs> + <func> + <name>error_msg(Format) -> ok</name> + <name>error_msg(Format, Data) -> ok</name> + <name>format(Format, Data) -> ok</name> + <fsummary>Send an standard error event to the error logger</fsummary> + <type> + <v>Format = string()</v> + <v>Data = [term()]</v> + </type> + <desc> + <p>Sends a standard error event to the error logger. + The <c>Format</c> and <c>Data</c> arguments are the same as + the arguments of <c>io:format/2</c>. The event is handled by + the standard event handler.</p> + <pre> +1> <input>error_logger:error_msg("An error occurred in ~p~n", [a_module]).</input> + +=ERROR REPORT==== 11-Aug-2005::14:03:19 === +An error occurred in a_module +ok</pre> + <warning> + <p>If called with bad arguments, this function can crash + the standard event handler, meaning no further events are + logged. When in doubt, use <c>error_report/1</c> instead.</p> + </warning> + </desc> + </func> + <func> + <name>error_report(Report) -> ok</name> + <fsummary>Send a standard error report event to the error logger</fsummary> + <type> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>Sends a standard error report event to the error logger. + The event is handled by the standard event handler.</p> + <pre> +2> <input>error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).</input> + +=ERROR REPORT==== 11-Aug-2005::13:45:41 === + tag1: data1 + a_term + tag2: data +ok +3> <input>error_logger:error_report("Serious error in my module").</input> + +=ERROR REPORT==== 11-Aug-2005::13:45:49 === +Serious error in my module +ok</pre> + </desc> + </func> + <func> + <name>error_report(Type, Report) -> ok</name> + <fsummary>Send a user defined error report event to the error logger</fsummary> + <type> + <v>Type = term()</v> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>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.</p> + <p>It is recommended that <c>Report</c> follows the same + structure as for <c>error_report/1</c>.</p> + </desc> + </func> + <func> + <name>warning_map() -> Tag</name> + <fsummary>Return the current mapping for warning events</fsummary> + <type> + <v>Tag = error | warning | info</v> + </type> + <desc> + <p>Returns the current mapping for warning events. Events sent + using <c>warning_msg/1,2</c> or <c>warning_report/1,2</c> + are tagged as errors (default), warnings or info, depending + on the value of the command line flag <c>+W</c>.</p> + <pre> +os$ <input>erl</input> +Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll] + +Eshell V5.4.8 (abort with ^G) +1> <input>error_logger:warning_map().</input> +error +2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).</input> + +=ERROR REPORT==== 11-Aug-2005::15:31:23 === +Warnings tagged as: error +ok +3> +User switch command + --> q +os$ <input>erl +W w</input> +Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll] + +Eshell V5.4.8 (abort with ^G) +1> <input>error_logger:warning_map().</input> +warning +2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).</input> + +=WARNING REPORT==== 11-Aug-2005::15:31:55 === +Warnings tagged as: warning +ok</pre> + </desc> + </func> + <func> + <name>warning_msg(Format) -> ok</name> + <name>warning_msg(Format, Data) -> ok</name> + <fsummary>Send a standard warning event to the error logger</fsummary> + <type> + <v>Format = string()</v> + <v>Data = [term()]</v> + </type> + <desc> + <p>Sends a standard warning event to the error logger. + The <c>Format</c> and <c>Data</c> arguments are the same as + the arguments of <c>io:format/2</c>. The event is handled by + the standard event handler. It is tagged either as an error, + warning or info, see + <seealso marker="#warning_map/0">warning_map/0</seealso>.</p> + <warning> + <p>If called with bad arguments, this function can crash + the standard event handler, meaning no further events are + logged. When in doubt, use <c>warning_report/1</c> instead.</p> + </warning> + </desc> + </func> + <func> + <name>warning_report(Report) -> ok</name> + <fsummary>Send a standard warning report event to the error logger</fsummary> + <type> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>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 + <seealso marker="#warning_map/0">warning_map/0</seealso>.</p> + </desc> + </func> + <func> + <name>warning_report(Type, Report) -> ok</name> + <fsummary>Send a user defined warning report event to the error logger</fsummary> + <type> + <v>Type = term()</v> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>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 + <seealso marker="#warning_map/0">warning_map/0</seealso>.</p> + </desc> + </func> + <func> + <name>info_msg(Format) -> ok</name> + <name>info_msg(Format, Data) -> ok</name> + <fsummary>Send a standard information event to the error logger</fsummary> + <type> + <v>Format = string()</v> + <v>Data = [term()]</v> + </type> + <desc> + <p>Sends a standard information event to the error logger. + The <c>Format</c> and <c>Data</c> arguments are the same as + the arguments of <c>io:format/2</c>. The event is handled by + the standard event handler.</p> + <pre> +1> <input>error_logger:info_msg("Something happened in ~p~n", [a_module]).</input> + +=INFO REPORT==== 11-Aug-2005::14:06:15 === +Something happened in a_module +ok</pre> + <warning> + <p>If called with bad arguments, this function can crash + the standard event handler, meaning no further events are + logged. When in doubt, use <c>info_report/1</c> instead.</p> + </warning> + </desc> + </func> + <func> + <name>info_report(Report) -> ok</name> + <fsummary>Send a standard information report event to the error logger</fsummary> + <type> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>Sends a standard information report event to the error + logger. The event is handled by the standard event handler.</p> + <pre> +2> <input>error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).</input> + +=INFO REPORT==== 11-Aug-2005::13:55:09 === + tag1: data1 + a_term + tag2: data +ok +3> <input>error_logger:info_report("Something strange happened").</input> + +=INFO REPORT==== 11-Aug-2005::13:55:36 === +Something strange happened +ok</pre> + </desc> + </func> + <func> + <name>info_report(Type, Report) -> ok</name> + <fsummary>Send a user defined information report event to the error logger</fsummary> + <type> + <v>Type = term()</v> + <v>Report = [{Tag, Data} | term()] | string() | term()</v> + <v> Tag = Data = term()</v> + </type> + <desc> + <p>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.</p> + <p>It is recommended that <c>Report</c> follows the same + structure as for <c>info_report/1</c>.</p> + </desc> + </func> + <func> + <name>add_report_handler(Handler) -> Result</name> + <name>add_report_handler(Handler, Args) -> Result</name> + <fsummary>Add an event handler to the error logger</fsummary> + <type> + <v>Handler, Args, Result -- see gen_event:add_handler/3</v> + </type> + <desc> + <p>Adds a new event handler to the error logger. The event + handler must be implemented as a <c>gen_event</c> callback + module, see + <seealso marker="stdlib:gen_event">gen_event(3)</seealso>.</p> + <p><c>Handler</c> is typically the name of the callback module + and <c>Args</c> is an optional term (defaults to []) passed + to the initialization callback function <c>Module:init/1</c>. + The function returns <c>ok</c> if successful.</p> + <p>The event handler must be able to handle the + <seealso marker="#events">events</seealso> described below.</p> + </desc> + </func> + <func> + <name>delete_report_handler(Handler) -> Result</name> + <fsummary>Delete an event handler from the error logger</fsummary> + <type> + <v>Handler, Result -- see gen_event:delete_handler/3</v> + </type> + <desc> + <p>Deletes an event handler from the error logger by calling + <c>gen_event:delete_handler(error_logger, Handler, [])</c>, + see <seealso marker="stdlib:gen_event">gen_event(3)</seealso>.</p> + </desc> + </func> + <func> + <name>tty(Flag) -> ok</name> + <fsummary>Enable or disable printouts to the tty</fsummary> + <type> + <v>Flag = bool()</v> + </type> + <desc> + <p>Enables (<c>Flag == true</c>) or disables + (<c>Flag == false</c>) printout of standard events to the tty.</p> + <p>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 <c>error_logger</c> configuration + parameter.</p> + </desc> + </func> + <func> + <name>logfile(Request) -> ok | Filename | {error, What}</name> + <fsummary>Enable or disable error printouts to a file</fsummary> + <type> + <v>Request = {open, Filename} | close | filename</v> + <v> Filename = atom() | string()</v> + <v>What = allready_have_logfile | no_log_file | term()</v> + </type> + <desc> + <p>Enables or disables printout of standard events to a file.</p> + <p>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 <c>error_logger</c> configuration + parameter.</p> + <p>Enabling file logging can be used in combination with calling + <c>tty(false)</c>, 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.</p> + <p><c>Request</c> is one of:</p> + <taglist> + <tag><c>{open, Filename}</c></tag> + <item> + <p>Opens the log file <c>Filename</c>. Returns <c>ok</c> if + successful, or <c>{error, allready_have_logfile}</c> if + logging to file is already enabled, or an error tuple if + another error occurred. For example, if <c>Filename</c> + could not be opened.</p> + </item> + <tag><c>close</c></tag> + <item> + <p>Closes the current log file. Returns <c>ok</c>, or + <c>{error, What}</c>.</p> + </item> + <tag><c>filename</c></tag> + <item> + <p>Returns the name of the log file <c>Filename</c>, or + <c>{error, no_log_file}</c> if logging to file is not + enabled.</p> + </item> + </taglist> + </desc> + </func> + </funcs> + + <section> + <marker id="events"></marker> + <title>Events</title> + <p>All event handlers added to the error logger must handle + the following events. <c>Gleader</c> is the group leader pid of + the process which sent the event, and <c>Pid</c> is the process + which sent the event.</p> + <taglist> + <tag><c>{error, Gleader, {Pid, Format, Data}}</c></tag> + <item> + <p>Generated when <c>error_msg/1,2</c> or <c>format</c> is + called.</p> + </item> + <tag><c>{error_report, Gleader, {Pid, std_error, Report}}</c></tag> + <item> + <p>Generated when <c>error_report/1</c> is called.</p> + </item> + <tag><c>{error_report, Gleader, {Pid, Type, Report}}</c></tag> + <item> + <p>Generated when <c>error_report/2</c> is called.</p> + </item> + <tag><c>{warning_msg, Gleader, {Pid, Format, Data}}</c></tag> + <item> + <p>Generated when <c>warning_msg/1,2</c> is called, provided + that warnings are set to be tagged as warnings.</p> + </item> + <tag><c>{warning_report, Gleader, {Pid, std_warning, Report}}</c></tag> + <item> + <p>Generated when <c>warning_report/1</c> is called, provided + that warnings are set to be tagged as warnings.</p> + </item> + <tag><c>{warning_report, Gleader, {Pid, Type, Report}}</c></tag> + <item> + <p>Generated when <c>warning_report/2</c> is called, provided + that warnings are set to be tagged as warnings.</p> + </item> + <tag><c>{info_msg, Gleader, {Pid, Format, Data}}</c></tag> + <item> + <p>Generated when <c>info_msg/1,2</c> is called.</p> + </item> + <tag><c>{info_report, Gleader, {Pid, std_info, Report}}</c></tag> + <item> + <p>Generated when <c>info_report/1</c> is called.</p> + </item> + <tag><c>{info_report, Gleader, {Pid, Type, Report}}</c></tag> + <item> + <p>Generated when <c>info_report/2</c> is called.</p> + </item> + </taglist> + <p>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 <c>Module:handle_event/2</c> + is necessary. This also holds true for + <c>Module:handle_info/2</c>, as there are a number of system + internal messages the event handler must take care of as well.</p> + </section> + + <section> + <title>SEE ALSO</title> + <p>gen_event(3), log_mf_h(3), kernel(6), sasl(6)</p> + </section> +</erlref> + |