aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/error_logger.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/error_logger.xml')
-rw-r--r--lib/kernel/doc/src/error_logger.xml381
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>