Update documentation of logger and error_logger

1 files changed, 148 insertions, 85 deletions

diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml
index e91fc734a4..f418aa5bbe 100644
--- a/lib/kernel/doc/src/error_logger.xml
+++ b/lib/kernel/doc/src/error_logger.xml
@@ -33,9 +33,10 @@
   <description>
 
     <note>
-      <p>In OTP-21, a new API for logging was added to Erlang/OTP. The
+      <p>In Erlang/OTP 21.0, a new API for logging was added. The
 	old <c>error_logger</c> module can still be used by legacy
-	code, but new code should use the new API instead.</p>
+	code, but log events are redirected to the new Logger API. New
+	code should use the Logger API directly.</p>
       <p><c>error_logger</c> is no longer started by default, but is
 	automatically started when an event handler is added
 	with <c>error_logger:add_report_handler/1,2</c>. The <c>error_logger</c>
@@ -89,6 +90,9 @@
           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>
+	<p>The first time this function is called,
+	  <c>error_logger</c> is added as a Logger handler, and
+	  the <c>error_logger</c> process is started.</p>
       </desc>
     </func>
     <func>
@@ -98,37 +102,40 @@
         <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>gen_event(3)</c></seealso>.</p>
+	<p>If no more event handlers exist after the deletion,
+	  <c>error_logger</c> is removed as a Logger handler, and
+	  the <c>error_logger</c> process is stopped.</p>
       </desc>
     </func>
     <func>
       <name name="error_msg" arity="1"/>
       <name name="error_msg" arity="2"/>
       <name name="format" arity="2"/>
-      <fsummary>Send a standard error event to the error logger.</fsummary>
+      <fsummary>Log a standard error event.</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
+        <p>Log a standard error event. 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 STDLIB.
-	  The event is handled by the standard event handler.</p>
+	  in STDLIB.</p>
+        <p>Error logger forwards the event to Logger, including
+          metadata that allows backwards compatibility with legacy
+          error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler.</p>
+	<p>These functions are kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_ERROR</c></seealso> macro or
+	  <seealso marker="logger#error-1"><c>logger:error/1,2,3</c></seealso>
+	  instead.</p>
 	<p><em>Example:</em></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 ===
+1> <input>error_logger:error_msg("An error occurred in ~p", [a_module]).</input>
+=ERROR REPORT==== 22-May-2018::11:18:43.376917 ===
 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
-	  <seealso marker="#error_report/1"><c>error_report/1</c></seealso>
-	  instead.</p>
-        </warning>
-        <warning>
           <p>If the Unicode translation modifier (<c>t</c>) is used in
-            the format string, all error handlers must ensure that the
+            the format string, all event handlers must ensure that the
             formatted output is correctly encoded for the I/O
             device.</p>
         </warning>
@@ -136,36 +143,51 @@ ok</pre>
     </func>
     <func>
       <name name="error_report" arity="1"/>
-      <fsummary>Send a standard error report event to the error logger.</fsummary>
+      <fsummary>Log a standard error event.</fsummary>
       <desc>
-        <p>Sends a standard error report event to the error logger.
-          The event is handled by the standard event handler.</p>
+        <p>Log a standard error event. Error logger forwards the event
+          to Logger, including metadata that allows backwards
+          compatibility with legacy error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_ERROR</c></seealso> macro or
+	  <seealso marker="logger#error-1"><c>logger:error/1,2,3</c></seealso>
+	  instead.</p>
 	<p><em>Example:</em></p>
         <pre>
 2> <input>error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).</input>
-
-=ERROR REPORT==== 11-Aug-2005::13:45:41 ===
+=ERROR REPORT==== 22-May-2018::11:24:23.699306 ===
     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 ===
+=ERROR REPORT==== 22-May-2018::11:24:45.972445 ===
 Serious error in my module
 ok</pre>
       </desc>
     </func>
     <func>
       <name name="error_report" arity="2"/>
-      <fsummary>Send a user-defined error report event to the error logger.</fsummary>
+      <fsummary>Log a user-defined error event.</fsummary>
       <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>Log a user-defined error event. Error logger forwards the
+          event to Logger, including metadata that allows backwards
+          compatibility with legacy error logger event handlers.</p>
+	<p>Error logger also adds a <c>domain</c> field with
+          value <c>[<anno>Type</anno>]</c> to this event's metadata,
+          causing the filters of the default Logger handler to discard
+          the event. A different Logger handler, or an error logger
+          event handler, must be added to handle this event.</p>
         <p>It is recommended that <c><anno>Report</anno></c> follows the same
           structure as for
 	<seealso marker="#error_report/1"><c>error_report/1</c></seealso>.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_ERROR</c></seealso> macro or
+	  <seealso marker="logger#error-1"><c>logger:error/1,2,3</c></seealso>
+	  instead.</p>
       </desc>
     </func>
     <func>
@@ -181,38 +203,41 @@ ok</pre>
 	  <p>The <c>error_logger_format_depth</c> variable
 	    is <seealso marker="kernel_app#deprecated-configuration-parameters">
 	    deprecated</seealso> since
-	    the <seealso marker="logger">logging API</seealso> was
-	    introduced in OTP-21. The variable, and this function, are
-	    kept for backwards compatibility since they still might be
-	    used by legacy report handlers.</p>
+	    the <seealso marker="logger">Logger API</seealso> was
+	    introduced in Erlang/OTP 21.0. The variable, and this
+	    function, are kept for backwards compatibility since they
+	    still might be used by legacy report handlers.</p>
 	</note>
       </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>Log a standard information event.</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
+        <p>Log a standard information event. 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 STDLIB. The event is handled by the standard event handler.</p>
+	  in STDLIB.</p>
+        <p>Error logger forwards the event to Logger, including
+          metadata that allows backwards compatibility with legacy
+          error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler.</p>
+	<p>These functions are kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_INFO</c></seealso> macro or
+	  <seealso marker="logger#info-1"><c>logger:info/1,2,3</c></seealso>
+	  instead.</p>
 	<p><em>Example:</em></p>
         <pre>
-1> <input>error_logger:info_msg("Something happened in ~p~n", [a_module]).</input>
-
-=INFO REPORT==== 11-Aug-2005::14:06:15 ===
+1> <input>error_logger:info_msg("Something happened in ~p", [a_module]).</input>
+=INFO REPORT==== 22-May-2018::12:03:32.612462 ===
 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>
-        <warning>
           <p>If the Unicode translation modifier (<c>t</c>) is used in
-            the format string, all error handlers must ensure that the
+            the format string, all event handlers must ensure that the
             formatted output is correctly encoded for the I/O
             device.</p>
         </warning>
@@ -220,37 +245,52 @@ ok</pre>
     </func>
     <func>
       <name name="info_report" arity="1"/>
-      <fsummary>Send a standard information report event to the error logger.</fsummary>
+      <fsummary>Log a standard information event.</fsummary>
       <desc>
-        <p>Sends a standard information report event to the error
-          logger. The event is handled by the standard event handler.</p>
+        <p>Log a standard information event. Error logger forwards the
+          event to Logger, including metadata that allows backwards
+          compatibility with legacy error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_INFO</c></seealso> macro or
+	  <seealso marker="logger#info-1"><c>logger:info/1,2,3</c></seealso>
+	  instead.</p>
 	<p><em>Example:</em></p>
         <pre>
 2> <input>error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).</input>
-
-=INFO REPORT==== 11-Aug-2005::13:55:09 ===
+=INFO REPORT==== 22-May-2018::12:06:35.994440 ===
     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 ===
+=INFO REPORT==== 22-May-2018::12:06:49.066872 ===
 Something strange happened
 ok</pre>
       </desc>
     </func>
     <func>
       <name name="info_report" arity="2"/>
-      <fsummary>Send a user-defined information report event to the error logger.</fsummary>
+      <fsummary>Log a user-defined information event.</fsummary>
       <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>Log a user-defined information event. Error logger forwards
+          the event to Logger, including metadata that allows
+          backwards compatibility with legacy error logger event
+          handlers.</p>
+	<p>Error logger also adds a <c>domain</c> field with
+          value <c>[<anno>Type</anno>]</c> to this event's metadata,
+          causing the filters of the default Logger handler to discard
+          the event. A different Logger handler, or an error logger
+          event handler, must be added to handle this event.</p>
         <p>It is recommended that <c><anno>Report</anno></c> follows the same
           structure as for
 	<seealso marker="#info_report/1"><c>info_report/1</c></seealso>.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_INFO</c></seealso> macro or
+	  <seealso marker="logger#info-1"><c>logger:info/1,2,3</c></seealso>
+	  instead.</p>
       </desc>
     </func>
     <func>
@@ -349,24 +389,27 @@ ok</pre>
     <func>
       <name name="warning_msg" arity="1"/>
       <name name="warning_msg" arity="2"/>
-      <fsummary>Send a standard warning event to the error logger.</fsummary>
+      <fsummary>Log a standard warning event.</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
+        <p>Log a standard warning event. 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 STDLIB.
-	  The event is handled by the standard event handler. It is tagged
-	  as an error, warning, or info, see
+	  in STDLIB.</p>
+        <p>Error logger forwards the event to Logger, including
+          metadata that allows backwards compatibility with legacy
+          error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler. The log
+	  level can be changed to error 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>
+	<p>These functions are kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_WARNING</c></seealso> macro or
+	  <seealso marker="logger#warning-1"><c>logger:warning/1,2,3</c></seealso>
+	  instead.</p>
         <warning>
           <p>If the Unicode translation modifier (<c>t</c>) is used in
-            the format string, all error handlers must ensure that the
+            the format string, all event handlers must ensure that the
             formatted output is correctly encoded for the I/O
             device.</p>
         </warning>
@@ -374,24 +417,43 @@ ok</pre>
     </func>
     <func>
       <name name="warning_report" arity="1"/>
-      <fsummary>Send a standard warning report event to the error logger.</fsummary>
+      <fsummary>Log a standard warning event.</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
+        <p>Log a standard warning event. Error logger forwards the event
+          to Logger, including metadata that allows backwards
+          compatibility with legacy error logger event handlers.</p>
+	<p>The event is handled by the default Logger handler. The log
+	  level can be changed to error or info, see
           <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_WARNING</c></seealso> macro or
+	  <seealso marker="logger#warning-1"><c>logger:warning/1,2,3</c></seealso>
+	  instead.</p>
       </desc>
     </func>
     <func>
       <name name="warning_report" arity="2"/>
-      <fsummary>Send a user-defined warning report event to the error logger.</fsummary>
+      <fsummary>Log a user-defined warning event.</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
+        <p>Log a user-defined warning event. Error logger forwards the
+          event to Logger, including metadata that allows backwards
+          compatibility with legacy error logger event handlers.</p>
+	<p>Error logger also adds a <c>domain</c> field with
+          value <c>[<anno>Type</anno>]</c> to this event's metadata,
+          causing the filters of the default Logger handler to discard
+          the event. A different Logger handler, or an error logger
+          event handler, must be added to handle this event.</p>
+	<p>The log level can be changed to error or info, see
           <seealso marker="#warning_map/0"><c>warning_map/0</c></seealso>.</p>
+        <p>It is recommended that <c><anno>Report</anno></c> follows the same
+          structure as for
+	<seealso marker="#warning_report/1"><c>warning_report/1</c></seealso>.</p>
+	<p>This functions is kept for backwards compatibility and
+	  must not be used by new code. Use the <seealso marker="logger#macros">
+	    <c>?LOG_WARNING</c></seealso> macro or
+	  <seealso marker="logger#warning-1"><c>logger:warning/1,2,3</c></seealso>
+	  instead.</p>
       </desc>
     </func>
   </funcs>
@@ -455,8 +517,9 @@ ok</pre>
   <section>
     <title>See Also</title>
     <p><seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>,
-       <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>
-       <seealso marker="kernel_app"><c>kernel(6)</c></seealso>
+       <seealso marker="kernel:logger"><c>logger(3)</c></seealso>,
+       <seealso marker="stdlib:log_mf_h"><c>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>