Update reference manuals for logger

1 files changed, 134 insertions, 79 deletions

diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml
index a0940100ee..7df4c88f40 100644
--- a/lib/kernel/doc/src/logger_formatter.xml
+++ b/lib/kernel/doc/src/logger_formatter.xml
@@ -33,43 +33,38 @@
     <file>logger_formatter.xml</file>
   </header>
   <module>logger_formatter</module>
-  <modulesummary>Default formatter for the Logger application.</modulesummary>
+  <modulesummary>Default formatter for Logger.</modulesummary>
 
   <description>
-    <p>Default formatter for the Logger application.</p>
-
+    <p>Each log handler has a configured formatter specified as a
+      module and a configuration term. The purpose of the formatter is
+      to translate the log events to a final printable string
+      (<c>unicode:chardata()</c>) which can be written to the output
+      device of the handler.</p>
+    <p><c>logger_formatter</c> is the default formatter used by
+      Logger.</p>
   </description>
 
   <section>
     <title>Configuration</title>
-    <p>The following configuration parameters can be set
-      for <c>logger_formatter</c>:</p>
+    <p>The configuration term for <c>logger_formatter</c> is a map,
+      and the following keys can be set as configuration
+      parameters:</p>
     <taglist>
-      <tag><c>single_line = boolean()</c></tag>
-      <item>
-	<p>If set to <c>true</c>, all newlines in the message are
-	  replaced with <c>", "</c>, and whitespaces following
-	  directly after newlines are removed. Note that newlines
-	  added by the formatter template are not replaced.</p>
-	<p>Default is <c>true</c>.</p>
-      </item>
-      <tag><c>legacy_header = boolen()</c></tag>
-      <item>
-	<p>If set to <c>true</c> a header field is added to
-	  logger_formatter's part of <c>Metadata</c>. The value of
-	  this field is a string similar to the header created by the
-	  old <c>error_logger</c> event handlers. It can be included
-	  in the log event by adding the
-	  tuple <c>{logger_formatter,header}</c> to the
-	  template. See <seealso marker="#default_templates">Default
-	  Templates</seealso> for more information</p>
-	<p>Default is <c>false</c>.</p>
-      </item>
-      <tag><c>report_cb = fun((logger:report()) -> {io:format(),[term()]})</c></tag>
+      <tag><c>chars_limit = pos_integer() | unlimited</c></tag>
       <item>
-	<p>A function with arity 1,
-	  returning <c>{Format,Args}</c>. This function will replace
-	  any <c>report_cb</c> found in metadata.</p>
+	<p>A positive integer representing the value of the option
+	  with the same name to be used when calling
+	  <seealso marker="stdlib:io_lib#format-3">io_lib:format/3</seealso>.
+	  This value limits the total number of characters printed
+	  for each log event. Notice that this is a soft limit. For a
+	  hard truncation limit, see option <c>max_size</c>.</p>
+	<p>Default is <c>unlimited</c>.</p>
+	<note>
+	  <p><c>chars_limit</c> has no effect on log messages on
+	    string form. These are expected to be short, but can still
+	    be truncated by the <c>max_size</c> parameter.</p>
+	</note>
       </item>
       <tag><c>depth = pos_integer() | unlimited</c></tag>
       <item>
@@ -82,47 +77,79 @@
 	  <seealso marker="stdlib:io#format-2">io:format/2,3</seealso>
 	  in STDLIB.</p>
 	<p>Default is <c>unlimited</c>.</p>
-      </item>
-      <tag><c>chars_limit = pos_integer() | unlimited</c></tag>
-      <item>
-	<p>A positive integer representing the value of the option
-	  with the same name to be used when calling
-	  <seealso marker="stdlib:io_lib#format-3">io_lib:format/3</seealso>.
-	  This value limits the total number of characters printed
-	  for each log event. Note that this is a soft limit. For a
-	  hard truncation limit, see option <c>max_size</c>.</p>
-	<p>Default is <c>unlimited</c>.</p>
+	<note>
+	  <p><c>depth</c> has no effect on log messages on string
+	    form. These are expected to be short, but can still be
+	    truncated by the <c>max_size</c> parameter.</p>
+	</note>
       </item>
       <tag><c>max_size = pos_integer() | unlimited</c></tag>
       <item>
-	<p>A positive integer representing the absolute maximum size
-	  a string returned from this formatter can have. If the
+	<p>A positive integer representing the absolute maximum size a
+	  string returned from this formatter can have. If the
 	  formatted string is longer, after possibly being limited
-	  by <c>depth</c> and/or <c>chars_limit</c>, it will be
-	  truncated.</p>
+	  by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p>
 	<p>Default is <c>unlimited</c>.</p>
       </item>
+      <tag><c>single_line = boolean()</c></tag>
+      <item>
+	<p>If set to <c>true</c>, all newlines in the message are
+	  replaced with <c>", "</c>, and whitespaces following
+	  directly after newlines are removed. Note that newlines
+	  added by the <c>template</c> parameter are not replaced.</p>
+	<p>Default is <c>true</c>.</p>
+      </item>
+      <tag><c>legacy_header = boolen()</c></tag>
+      <item>
+	<p>If set to <c>true</c> a header field is added to
+	  logger_formatter's part of <c>Metadata</c>. The value of
+	  this field is a string similar to the header created by the
+	  old <c>error_logger</c> event handlers. It can be included
+	  in the log event by adding the
+	  tuple <c>{logger_formatter,header}</c> to the template. See
+	  section <seealso marker="#default_templates">Default
+	  Templates</seealso> for more information.</p>
+	<p>Default is <c>false</c>.</p>
+      </item>
+      <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>,[term()]})</c></tag>
+      <item>
+	<p>A report callback is used by the formatter to transform log
+	  messages on report form to a format string and
+	  arguments. The report callback can be specified in the
+	  metadata for the log event. If no report callback exist in
+	  metadata, <c>logger_formatter</c> will
+	  use <seealso marker="logger#format_report-1">
+	    <c>logger:format_report/1</c></seealso> as default
+	  callback.</p>
+	<p>If this configuration parameter is set, it replaces both
+	  the default report callback, and any report callback found
+	  in metadata. That is, all reports are converted by this
+	  configured function.</p>
+	<p>The value must be a function with arity 1,
+	  returning <c>{Format,Args}</c>, and it will be called with a
+	  report as only argument.</p>
+      </item>
       <tag><c>template = </c><seealso marker="#type-template"><c>template()</c></seealso></tag>
       <item>
 	<p>The template is a list of atoms, tuples and strings. The
 	  atoms <c>level</c> or <c>msg</c>, are treated as
 	  placeholders for the severity level and the log message,
 	  repectively. Other atoms or tuples are interpreted as
-	  placeholders for metadata, where atoms are expected to
-	  match top level keys, and tuples represent paths to sub
-	  keys in a nested map. For example the
-	  tuple <c>{key1,key2}</c> will be replaced by the value of
+	  placeholders for metadata, where atoms are expected to match
+	  top level keys, and tuples represent paths to sub keys when
+	  the metadata is a nested map. For example the
+	  tuple <c>{key1,key2}</c> is replaced by the value of
 	  the <c>key2</c> field in the nested map below. The
-	  atom <c>key1</c> on its own would be replaced by the
-	  complete value of the <c>key1</c> field. The values are
-	  converted to strings.</p>
+	  atom <c>key1</c> on its own is replaced by the complete
+	  value of the <c>key1</c> field. The values are converted to
+	  strings.</p>
 
 <code>
 #{key1=>#{key2=>my_value,
           ...}
   ...}</code>
 
-        <p>Strings are printed literally.</p>
+        <p>Strings in the template are printed literally.</p>
 	<p>The default template differs depending on the values
 	  of <c>legacy_header</c>
 	  and <c>single_line</c>. See <seealso marker="#default_templates">Default
@@ -131,7 +158,8 @@
       <tag><c>utc = boolean()</c></tag>
       <item>
 	<p>If set to <c>true</c>, all dates are displayed in Universal
-	  Coordinated Time. Default is <c>false</c>.</p>
+	  Coordinated Time.</p>
+	<p>Default is <c>false</c>.</p>
       </item>
     </taglist>
   </section>
@@ -139,38 +167,51 @@
   <section>
     <marker id="default_templates"/>
     <title>Default templates</title>
-    <p>The default template when <c>legacy_header=true</c> is</p>
-
-    <code>[{logger_formatter,header},"\n",msg,"\n"]</code>
-
-    <p>which will cause log entries like this:</p>
-
-    <code>=ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
-    process: &lt;0.74.0&gt;
-    exit_reason: "Something went wrong"</code>
-
-    <p>Note that all eight levels might occur here, not
-      only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c>. And also that
-      micro seconds are added at the end of the timestamp.</p>
-
-    <p>The default template when <c>single_line=true</c> is</p>
 
-    <code>[time," ",level,": ",msg,"\n"]</code>
+    <p>The default value for the <c>template</c> configuration
+      parameter depends on the value of <c>single_line</c>
+      and <c>legacy_header</c> as follows.</p>
 
-    <p>which will cause log entries like this:</p>
+    <p>The log event used in the examples is:</p>
+    <code>
+?LOG_ERROR("name: ~p~nexit_reason: ~p",[my_reg_name,"It crashed"])</code>
 
-    <code>2017-12-29 13:31:49.640317 error: process: &lt;0.74.0&gt;, exit_reason: "Something went wrong"</code>
+    <taglist>
+      <tag><c>legacy_header=true</c></tag>
+      <item>
+	<p>Default template: <c>[{logger_formatter,header},"\n",msg,"\n"]</c></p>
+
+	<p>Example log entry:</p>
+	<code>
+=ERROR REPORT==== 29-Dec-2017::13:30:51.245123 ===
+name: my_reg_name
+exit_reason: "It crashed"</code>
+
+	<p>Notice that all eight levels might occur in the heading,
+	  not only <c>ERROR</c>, <c>WARNING</c> or <c>INFO</c> as the
+	  old <c>error_logger</c> produced. And microseconds are
+	  added at the end of the timestamp.</p>
+      </item>
 
-    <p>The default template when both <c>legacy_header</c> and
-      <c>single_line</c> are set to false is:</p>
+      <tag><c>single_line=true</c></tag>
+      <item>
+	<p>Default template: <c>[time," ",level,": ",msg,"\n"]</c></p>
 
-    <code>[time," ",level,":\n",msg,"\n"]</code>
+	<p>Example log entry:</p>
+	<code>2017-12-29 13:31:49.640317 error: name: my_reg_name, exit_reason: "It crashed"</code>
+      </item>
 
-    <p>which will cause log entries like this:</p>
+      <tag><c>legacy_header=false, single_line=false</c></tag>
+      <item>
+	<p>Default template: <c>[time," ",level,":\n",msg,"\n"]</c></p>
 
-    <code>2017-12-29 13:32:25.191925 error:
-    process: &lt;0.74.0&gt;
-    exit_reason: "Something went wrong"</code>
+	<p>Example log entry:</p>
+	<code>
+2017-12-29 13:32:25.191925 error:
+name: my_reg_name
+exit_reason: "It crashed"</code>
+      </item>
+    </taglist>
   </section>
 
   <datatypes>
@@ -186,8 +227,22 @@
       <name name="format" arity="2"/>
       <fsummary>Formats the given message.</fsummary>
       <desc>
-	<p>This the callback function to be called from handlers. It
-	  formats the given messages.</p>
+	<p>This the formatter callback function to be called from
+	  handlers. The log event is processed as follows:</p>
+	<list>
+	  <item>If the message is on report form, it is converted to
+	    <c>{Format,Args}</c> by calling the report
+	    callback.</item>
+	  <item>The size is limited according to the values of
+	    configuration parameters <c>chars_limit</c>
+	    and <c>depth</c>. Notice that this does not apply to
+	    messages on string form.</item>
+	  <item>The full log entry is composed according to
+	    the <c>template</c>.</item>
+	  <item>If the final string is too long, it is truncated
+	    according to the value of configuration
+	    parameter <c>max_size</c>.</item>
+	</list>
       </desc>
     </func>