diff options
Diffstat (limited to 'lib/kernel/doc/src/error_logger.xml')
| -rw-r--r-- | lib/kernel/doc/src/error_logger.xml | 381 |
1 files changed, 200 insertions, 181 deletions
diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index 92e14c2bef..3bd192fd41 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -29,41 +29,44 @@ <rev></rev> </header> <module>error_logger</module> - <modulesummary>Erlang Error Logger</modulesummary> + <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 + <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>), + registered as <c>error_logger</c>. 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 tty. Note that an event from a process <c>P</c> is + logged to the terminal. Notice 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 + <p>Initially, <c>error_logger</c> has only 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> + system startup, the <c>Kernel</c> application replaces this with a + <em>standard event handler</em>, by default one that writes + nicely formatted output to the terminal. <c>Kernel</c> can also be + configured so that events are logged to a file instead, or not logged at all, + see <seealso marker="kernel_app"><c>kernel(6)</c></seealso>.</p> + <p>Also the <c>SASL</c> application, if started, adds its own event + handler, which by default writes supervisor, crash, and progress + reports to the terminal. See + <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso>.</p> + <p>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 + <seealso marker="#add_report_handler/1"><c>add_report_handler/1,2</c></seealso>. + Also, a useful event handler is provided in <c>STDLIB</c> for multi-file + logging of events, see + <seealso marker="stdlib:log_mf_h"><c>stdlib:log_mf_h(3)</c></seealso>.</p> <p>Warning events were introduced in Erlang/OTP R9C and are enabled - by default as of 18.0. To retain backwards compatibility with existing - user defined event handlers, these may be tagged as errors or info - using the command line flag <c><![CDATA[+W <e | i | w>]]></c>, thus - showing up as error or info reports in the logs.</p> + 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 <c>errors</c> or <c>info</c> using command-line flag + <c><![CDATA[+W <e | i | w>]]></c>, thus showing up as + <c>ERROR REPORT</c> or <c>INFO REPORT</c> in the logs.</p> </description> <datatypes> <datatype> @@ -72,15 +75,44 @@ </datatypes> <funcs> <func> + <name name="add_report_handler" arity="1"/> + <name name="add_report_handler" arity="2"/> + <fsummary>Add an event handler to the error logger.</fsummary> + <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"><c>stdlib:gen_event(3)</c></seealso>.</p> + <p><c><anno>Handler</anno></c> is typically the name of the callback module + and <c><anno>Args</anno></c> is an optional term (defaults to []) passed + to the initialization callback function <c><anno>Handler</anno>:init/1</c>. + The function returns <c>ok</c> if successful.</p> + <p>The event handler must be able to handle the events in this module, see + section <seealso marker="#events">Events</seealso>.</p> + </desc> + </func> + <func> + <name name="delete_report_handler" arity="1"/> + <fsummary>Delete an event handler from the error logger.</fsummary> + <desc> + <p>Deletes an event handler from the error logger by calling + <c>gen_event:delete_handler(error_logger, <anno>Handler</anno>, [])</c>, + see <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.</p> + </desc> + </func> + <func> <name name="error_msg" arity="1"/> <name name="error_msg" arity="2"/> <name name="format" arity="2"/> - <fsummary>Send an standard error event to the error logger</fsummary> + <fsummary>Send a standard error event to the error logger.</fsummary> <desc> <p>Sends a standard error event to the error logger. - The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments are the same as - the arguments of <c>io:format/2</c>. The event is handled by - the standard event handler.</p> + The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments + are the same as the arguments of + <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso> + in <c>STDLIB</c>. + The event is handled by the standard event handler.</p> + <p><em>Example:</em></p> <pre> 1> <input>error_logger:error_msg("An error occurred in ~p~n", [a_module]).</input> @@ -90,16 +122,19 @@ 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> + logged. When in doubt, use + <seealso marker="#error_report/1"><c>error_report/1</c></seealso> + instead.</p> </warning> </desc> </func> <func> <name name="error_report" arity="1"/> - <fsummary>Send a standard error report event to the error logger</fsummary> + <fsummary>Send a standard error report event to the error logger.</fsummary> <desc> <p>Sends a standard error report event to the error logger. The event is handled by the standard event handler.</p> + <p><em>Example:</em></p> <pre> 2> <input>error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).</input> @@ -117,100 +152,27 @@ ok</pre> </func> <func> <name name="error_report" arity="2"/> - <fsummary>Send a user defined error report event to the error logger</fsummary> + <fsummary>Send a user-defined error report event to the error logger.</fsummary> <desc> - <p>Sends a user defined error report event to the error logger. + <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><anno>Report</anno></c> follows the same - structure as for <c>error_report/1</c>.</p> - </desc> - </func> - <func> - <name name="warning_map" arity="0"/> - <fsummary>Return the current mapping for warning events</fsummary> - <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, warnings (default) 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> -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 -3> -User switch command - --> q -os$ <input>erl +W e</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</pre> - </desc> - </func> - <func> - <name name="warning_msg" arity="1"/> - <name name="warning_msg" arity="2"/> - <fsummary>Send a standard warning event to the error logger</fsummary> - <desc> - <p>Sends a standard warning event to the error logger. - The <c><anno>Format</anno></c> and <c><anno>Data</anno></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 name="warning_report" arity="1"/> - <fsummary>Send a standard warning report event to the error logger</fsummary> - <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 name="warning_report" arity="2"/> - <fsummary>Send a user defined warning report event to the error logger</fsummary> - <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> + structure as for + <seealso marker="#error_report/1"><c>error_report/1</c></seealso>.</p> </desc> </func> <func> <name name="info_msg" arity="1"/> <name name="info_msg" arity="2"/> - <fsummary>Send a standard information event to the error logger</fsummary> + <fsummary>Send a standard information event to the error logger.</fsummary> <desc> <p>Sends a standard information event to the error logger. - The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments are the same as - the arguments of <c>io:format/2</c>. The event is handled by - the standard event handler.</p> + The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments + are the same as the arguments of + <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso> + in <c>STDLIB</c>. The event is handled by the standard event handler.</p> + <p><em>Example:</em></p> <pre> 1> <input>error_logger:info_msg("Something happened in ~p~n", [a_module]).</input> @@ -226,10 +188,11 @@ ok</pre> </func> <func> <name name="info_report" arity="1"/> - <fsummary>Send a standard information report event to the error logger</fsummary> + <fsummary>Send a standard information report event to the error logger.</fsummary> <desc> <p>Sends a standard information report event to the error logger. The event is handled by the standard event handler.</p> + <p><em>Example:</em></p> <pre> 2> <input>error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).</input> @@ -247,59 +210,22 @@ ok</pre> </func> <func> <name name="info_report" arity="2"/> - <fsummary>Send a user defined information report event to the error logger</fsummary> + <fsummary>Send a user-defined information report event to the error logger.</fsummary> <desc> - <p>Sends a user defined information report event to the error + <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><anno>Report</anno></c> follows the same - structure as for <c>info_report/1</c>.</p> - </desc> - </func> - <func> - <name name="add_report_handler" arity="1"/> - <name name="add_report_handler" arity="2"/> - <fsummary>Add an event handler to the error logger</fsummary> - <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><anno>Handler</anno></c> is typically the name of the callback module - and <c><anno>Args</anno></c> is an optional term (defaults to []) passed - to the initialization callback function <c><anno>Handler</anno>: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 name="delete_report_handler" arity="1"/> - <fsummary>Delete an event handler from the error logger</fsummary> - <desc> - <p>Deletes an event handler from the error logger by calling - <c>gen_event:delete_handler(error_logger, <anno>Handler</anno>, [])</c>, - see <seealso marker="stdlib:gen_event">gen_event(3)</seealso>.</p> - </desc> - </func> - <func> - <name name="tty" arity="1"/> - <fsummary>Enable or disable printouts to the tty</fsummary> - <desc> - <p>Enables (<c><anno>Flag</anno> == true</c>) or disables - (<c><anno>Flag</anno> == 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> + structure as for + <seealso marker="#info_report/1"><c>info_report/1</c></seealso>.</p> </desc> </func> <func> <name name="logfile" arity="1" clause_i="1"/> <name name="logfile" arity="1" clause_i="2"/> <name name="logfile" arity="1" clause_i="3"/> - <fsummary>Enable or disable error printouts to a file</fsummary> + <fsummary>Enable or disable error printouts to a file.</fsummary> <type variable="Filename"/> <type variable="OpenReason" name_i="1"/> <type variable="CloseReason" name_i="2"/> @@ -308,22 +234,22 @@ ok</pre> <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 + for output to file. Thus, calling this function overrides + the value of the <c>Kernel</c> <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 + <p>Enabling file logging can be used together with calling + <c>tty(false)</c>, 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> + Only one log file can be active at a time.</p> + <p><c>Request</c> is one of the following:</p> <taglist> <tag><c>{open, <anno>Filename</anno>}</c></tag> <item> - <p>Opens the log file <c><anno>Filename</anno></c>. Returns <c>ok</c> if + <p>Opens log file <c><anno>Filename</anno></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><anno>Filename</anno></c> - could not be opened.</p> + another error occurred (for example, if <c><anno>Filename</anno></c> + cannot be opened).</p> </item> <tag><c>close</c></tag> <item> @@ -339,6 +265,97 @@ ok</pre> </taglist> </desc> </func> + <func> + <name name="tty" arity="1"/> + <fsummary>Enable or disable printouts to the terminal.</fsummary> + <desc> + <p>Enables (<c><anno>Flag</anno> == true</c>) or disables + (<c><anno>Flag</anno> == false</c>) printout of standard events + to the terminal.</p> + <p>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 <c>Kernel</c> <c>error_logger</c> configuration parameter.</p> + </desc> + </func> + <func> + <name name="warning_map" arity="0"/> + <fsummary>Return the current mapping for warning events.</fsummary> + <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, warnings (default), or info, depending + on the value of command-line flag <c>+W</c>.</p> + <p><em>Example:</em></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> +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 +3> +User switch command + --> q +os$ <input>erl +W e</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</pre> + </desc> + </func> + <func> + <name name="warning_msg" arity="1"/> + <name name="warning_msg" arity="2"/> + <fsummary>Send a standard warning event to the error logger.</fsummary> + <desc> + <p>Sends a standard warning event to the error logger. + The <c><anno>Format</anno></c> and <c><anno>Data</anno></c> arguments + are the same as the arguments of + <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso> + in <c>STDLIB</c>. + The event is handled by the standard event handler. It is tagged + as an error, warning, or info, see + <seealso marker="#warning_map/0"><c>warning_map/0</c></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 name="warning_report" arity="1"/> + <fsummary>Send a standard warning report event to the error logger.</fsummary> + <desc> + <p>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 + <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p> + </desc> + </func> + <func> + <name name="warning_report" arity="2"/> + <fsummary>Send a user-defined warning report event to the error logger.</fsummary> + <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 as an error, warning, or info, + depending on the value of + <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p> + </desc> + </func> </funcs> <section> @@ -346,8 +363,8 @@ ok</pre> <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> + the process that sent the event, and <c>Pid</c> is the process + that sent the event.</p> <taglist> <tag><c>{error, Gleader, {Pid, Format, Data}}</c></tag> <item> @@ -364,18 +381,18 @@ ok</pre> </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> + <p>Generated when <c>warning_msg/1,2</c> is called + if 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> + <p>Generated when <c>warning_report/1</c> is called + if 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> + <p>Generated when <c>warning_report/2</c> is called + if warnings are set to be tagged as warnings.</p> </item> <tag><c>{info_msg, Gleader, {Pid, Format, Data}}</c></tag> <item> @@ -390,17 +407,19 @@ ok</pre> <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 + <p>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 <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> + is necessary. This also applies for + <c>Module:handle_info/2</c>, as the event handler must also take care of + some system-internal messages.</p> </section> - <section> - <title>SEE ALSO</title> - <p>gen_event(3), log_mf_h(3), kernel(6), sasl(6)</p> + <title>See Also</title> + <p><seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>, + <seealso marker="stdlib:log_mf_h"><c>stdlib:log_mf_h(3)</c></seealso> + <seealso marker="kernel_app"><c>kernel(6)</c></seealso> + <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso></p> </section> </erlref> |