Merge branch 'siri/logger-fix'

* siri/logger-fix:
  Update reference manuals for logger
  Update some specs in logger

3 files changed, 455 insertions, 143 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 2f7feb5eef..d901454e62 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -67,37 +67,86 @@
     <datatype>
       <name name="metadata"/>
       <desc>
-	<p>Metadata associated with the message to be logged.</p>
+	<p>Metadata for the log event.</p>
+	<p>Logger adds the following metadata to each log event:</p>
+	<list>
+	  <item><c>pid  => self()</c></item>
+	  <item><c>gl   => group_leader()</c></item>
+	  <item><c>time => erlang:monotonic_time(microsecond)</c></item>
+	</list>
+	<p>When a log macro is used, Logger also inserts location
+	  information:</p>
+	<list>
+	  <item><c>mfa  => {?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY}</c></item>
+	  <item><c>file => ?FILE</c></item>
+	  <item><c>line => ?LINE</c></item>
+	</list>
+	<p>You can add custom metadata, either by specifying a map as
+	  the last parameter to any of the log macros or the API
+	  functions, or by setting process metadata
+	  with <seealso marker="#set_process_metadata-1">
+	    <c>set_process_metadata/1</c></seealso>
+	  or <seealso marker="#update_process_metadata-1">
+	    <c>update_process_metadata/1</c></seealso>.</p>
+	<p>Logger merges all the metadata maps before forwarding the
+	  log event to the handlers. If the same keys occur, values
+	  from the log call overwrites process metadata, which in turn
+	  overwrites values set by Logger.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="config"/>
       <desc>
-	<p></p>
+	<p>Configuration data for the logger part of Logger, or for a handler.</p>
+	<p>The following default values apply:</p>
+	<list>
+	  <item><c>level => info</c></item>
+	  <item><c>filter_default => log</c></item>
+	  <item><c>filters => []</c></item>
+	  <item><c>formatter => {logger_formatter,DefaultFormatterConfig</c>}</item>
+	</list>
+	<p>See the <seealso marker="logger_formatter#configuration">
+	    <c>logger_formatter(3)</c></seealso> manual page for
+	  information about the default configuration for this
+	  formatter.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="handler_id"/>
       <desc>
-	<p></p>
+	<p>A unique identifier for a handler instance.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="filter_id"/>
       <desc>
-	<p></p>
+	<p>A unique identifier for a filter.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="filter"/>
       <desc>
-	<p></p>
+	<p>A filter which can be installed for logger or for a handler.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="filter_arg"/>
+      <desc>
+	<p>The second argument to the filter fun.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="filter_return"/>
       <desc>
-	<p></p>
+	<p>The return value from the filter fun.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="timestamp"/>
+      <desc>
+	<p>A timestamp produced
+	  with <seealso marker="erts:erlang#monotonic_time-1">
+	    <c>erlang:monotonic_time(microsecond)</c></seealso>.</p>
       </desc>
     </datatype>
   </datatypes>
@@ -126,14 +175,10 @@
     </list>
 
     <p>All macros expand to a call to logger, where <c>Level</c> is
-      taken from the macro name, and the following metadata is added,
-      or merged with the given <c>Metadata</c>:</p>
-
-    <code>
-#{mfa=>{?MODULE,?FUNCTION_NAME,?FUNCTION_ARITY},
-  file=>?FILE,
-  line=>?LINE}
-    </code>
+      taken from the macro name, and location data is added. See the
+      description of
+      the <seealso marker="#type-metadata"><c>metadata()</c></seealso>
+      type for more information about the location data.</p>
 
     <p>The call is wrapped in a case statement and will be evaluated
       only if <c>Level</c> is equal to or below the configured log
@@ -267,7 +312,7 @@
 
     <func>
       <name name="i" arity="0"/>
-      <fsummary>Get information about all logger configurations</fsummary>
+      <fsummary>Get all logger configurations</fsummary>
       <desc>
         <p>Same as <seealso marker="#i/1"><c>logger:i(term)</c></seealso></p>
       </desc>
@@ -277,26 +322,29 @@
       <name name="i" arity="1" clause_i="1"/>
       <name name="i" arity="1" clause_i="2"/>
       <name name="i" arity="1" clause_i="3"/>
-      <fsummary>Get information about all logger configurations</fsummary>
+      <fsummary>Get all logger configurations</fsummary>
       <desc>
-        <p>The <c>logger:i/1</c> function can be used to get all
-          current logger configuration.  The way that the information
-          is returned depends on the <c><anno>Action</anno></c></p>
+        <p>Display or return all current logger configuration.</p>
         <taglist>
-          <tag>string</tag>
-          <item>Return the pretty printed current logger configuration
-            as iodata.</item>
-          <tag>term</tag>
-          <item>Return the current logger configuration as a term. The
-            format of this term may change inbetween releases. For a
-            stable format use <seealso marker="#get_handler_config/1">
+          <tag><c><anno>Action</anno> = string</c></tag>
+          <item>
+	    <p>Return the pretty printed current logger configuration
+              as iodata.</p>
+	  </item>
+          <tag><c><anno>Action</anno> = term</c></tag>
+          <item>
+	    <p>Return the current logger configuration as a term. The
+              format of this term may change inbetween releases. For a
+              stable format use <seealso marker="#get_handler_config/1">
 	      <c>logger:get_handler_config/1</c></seealso>
-            and <seealso marker="#get_logger_config/0">
+              and <seealso marker="#get_logger_config/0">
 	      <c>logger:get_logger_config/0</c></seealso>.
-            The same as calling <c>logger:i()</c>.</item>
-	  <tag>print</tag>
-          <item>Pretty print all the current logger configuration to
-            standard out. Example:
+              The same as calling <c>logger:i()</c>.</p>
+	  </item>
+	  <tag><c><anno>Action</anno> = print</c></tag>
+          <item>
+	    <p>Pretty print all the current logger configuration to
+              standard out. Example:</p>
             <code><![CDATA[1> logger:i(print).
 Current logger configuration:
   Level: info
@@ -339,6 +387,39 @@ Current logger configuration:
       <fsummary>Add a filter to the logger.</fsummary>
       <desc>
         <p>Add a filter to the logger.</p>
+	<p>The filter fun is called with the log event as the first
+	  parameter, and the specified <c>filter_args()</c> as the
+	  second parameter.</p>
+	<p>The return value of the fun specifies if a log event is to
+	  be discarded or forwarded to the handlers:</p>
+	<taglist>
+	  <tag><c>log()</c></tag>
+	  <item>
+	    <p>The filter <em>passed</em>. The next logger filter, if
+	      any, is applied. If no more logger filters exist, the
+	      log event is forwarded to the handler part of the
+	      logger, where handler filters are applied.</p>
+	  </item>
+	  <tag><c>stop</c></tag>
+	  <item>
+	    <p>The filter <em>did not pass</em>, and the log event is
+	      immediately discarded.</p>
+	  </item>
+	  <tag><c>ignore</c></tag>
+	  <item>
+	    <p>The filter has no knowledge of the log event. The next
+	      logger filter, if any, is applied. If no more logger
+	      filters exist, the value of the <c>filter_default</c>
+	      configuration parameter for the logger specifies if the
+	      log event shall be discarded or forwarded to the handler
+	      part.</p>
+	  </item>
+	</taglist>
+	<p>See section <seealso marker="logger_chapter#Filter">
+	    Filter</seealso> in the User's Guide for more information
+	    about filters.</p>
+	<p>Some built-in filters exist. These are defined
+	  in <seealso marker="logger_filters"><c>logger_filters</c></seealso>.</p>
       </desc>
     </func>
 
@@ -347,6 +428,39 @@ Current logger configuration:
       <fsummary>Add a filter to the specified handler.</fsummary>
       <desc>
         <p>Add a filter to the specified handler.</p>
+	<p>The filter fun is called with the log event as the first
+	  parameter, and the specified <c>filter_args()</c> as the
+	  second parameter.</p>
+	<p>The return value of the fun specifies if a log event is to
+	  be discarded or forwarded to the handler callback:</p>
+	<taglist>
+	  <tag><c>log()</c></tag>
+	  <item>
+	    <p>The filter <em>passed</em>. The next handler filter, if
+	      any, is applied. If no more filters exist for this
+	      handler, the log event is forwarded to the handler
+	      callback.</p>
+	  </item>
+	  <tag><c>stop</c></tag>
+	  <item>
+	    <p>The filter <em>did not pass</em>, and the log event is
+	      immediately discarded.</p>
+	  </item>
+	  <tag><c>ignore</c></tag>
+	  <item>
+	    <p>The filter has no knowledge of the log event. The next
+	      handler filter, if any, is applied. If no more filters
+	      exist for this handler, the value of
+	      the <c>filter_default</c> configuration parameter for
+	      the handler specifies if the log event shall be
+	      discarded or forwarded to the handler callback.</p>
+	  </item>
+	</taglist>
+	<p>See
+	  section <seealso marker="logger_chapter#Filter">Filter</seealso>
+	  in the User's Guide for more information about filters.</p>
+	<p>Some built-in filters exist. These are defined in
+	  <seealso marker="logger_filters"><c>logger_filters</c></seealso>.</p>
       </desc>
     </func>
 
@@ -354,7 +468,8 @@ Current logger configuration:
       <name name="remove_logger_filter" arity="1"/>
       <fsummary>Remove a filter from the logger.</fsummary>
       <desc>
-        <p>Remove the filter with the specified identity from the logger.</p>
+        <p>Remove the filter identified
+          by <c><anno>FilterId</anno></c> from the logger.</p>
       </desc>
     </func>
 
@@ -362,7 +477,9 @@ Current logger configuration:
       <name name="remove_handler_filter" arity="2"/>
       <fsummary>Remove a filter from the specified handler.</fsummary>
       <desc>
-        <p>Remove the filter with the specified identity from the given handler.</p>
+        <p>Remove the filter identified
+          by <c><anno>FilterId</anno></c> from the handler identified
+          by <c><anno>HandlerId</anno></c>.</p>
       </desc>
     </func>
 
@@ -371,6 +488,9 @@ Current logger configuration:
       <fsummary>Add a handler with the given configuration.</fsummary>
       <desc>
         <p>Add a handler with the given configuration.</p>
+	<p><c><anno>HandlerId</anno></c> is a unique identifier which
+	  must be used in all subsequent calls reffering to this
+	  handler.</p>
       </desc>
     </func>
 
@@ -378,7 +498,7 @@ Current logger configuration:
       <name name="remove_handler" arity="1"/>
       <fsummary>Remove the handler with the specified identity.</fsummary>
       <desc>
-        <p>Remove the handler with the specified identity.</p>
+        <p>Remove the handler identified by <c><anno>HandlerId</anno></c>.</p>
       </desc>
     </func>
 
@@ -386,10 +506,37 @@ Current logger configuration:
       <name name="set_module_level" arity="2"/>
       <fsummary>Set the log level for the specified module.</fsummary>
       <desc>
-        <p>Set the log level for the specified module.</p>
-        <p>To change the logging level globally, use
-        <seealso marker="#set_logger_config/2"><c>logger:set_logger_config(level, Level)</c></seealso>.
-        </p>
+        <p>Set the log level for the
+          specified <c><anno>Module</anno></c>.</p>
+	<p>The log level for a module overrides the global log level
+	  of the logger for log event originating from the module in
+	  question. Notice, however, that it does not override the
+	  level configuration for any handler.</p>
+	<p>For example: Assume that the global log level for the
+	  logger is <c>info</c>, and there is one handler, <c>h1</c>,
+	  with level <c>info</c> and one handler, <c>h2</c>, with
+	  level <c>debug</c>.</p>
+	<p>With this configuration, no debug messages will be logged,
+	  since they are all stopped by the global log level.</p>
+	<p>If the level for <c>mymodule</c> is set now set
+	  to <c>debug</c>, then debug events from this module will be
+	  logged by the handler <c>h2</c>, but not by
+	  handler <c>h1</c>.</p>
+	<p>Debug events from other modules are still not logged.</p>
+        <p>To change the global log level for the logger, use
+          <seealso marker="#set_logger_config/2">
+	    <c>logger:set_logger_config(level,Level)</c></seealso>.</p>
+        <p>To change the log level for a handler, use
+          <seealso marker="#set_handler_config/3">
+	    <c>logger:set_handler_config(HandlerId,level,Level)</c></seealso>.</p>
+	<note>
+	  <p>The originating module for a log event is only detected
+	    if <c>mfa=>{Module,Function,Arity}</c> exists in the
+	    metadata. When log macros are used, this association is
+	    automatically added to all log events. If the logger API
+	    is called directly, without using a macro, the logging
+	    client must explicitly add this information.</p>
+	</note>
       </desc>
     </func>
 
@@ -414,6 +561,8 @@ Current logger configuration:
 	  with <seealso marker="#get_logger_config-0"><c>get_logger_config/0</c>
 	  </seealso>, then merge in your added or updated
 	  associations before writing it back.</p>
+	<p>If a key is removed compared to the current configuration,
+	  the default value is used.</p>
       </desc>
     </func>
 
@@ -423,7 +572,7 @@ Current logger configuration:
       <desc>
         <p>Add or update configuration data for the logger. If the
           given <c><anno>Key</anno></c> already exists, its associated
-          value will be set to <c><anno>Value</anno></c>. If it
+          value will be changed to <c><anno>Value</anno></c>. If it
           doesn't exist, it will be added.</p>
       </desc>
     </func>
@@ -440,6 +589,11 @@ Current logger configuration:
 	  with <seealso marker="#get_handler_config-1"><c>get_handler_config/1</c>
 	  </seealso>, then merge in your added or updated
 	  associations before writing it back.</p>
+	<p>If a key is removed compared to the current configuration,
+	  and the key is know by Logger, the default value is used. If
+	  it is a custom key, then it is up to the handler
+	  implementation if the value is removed or a default value is
+	  inserted.</p>
       </desc>
     </func>
 
@@ -449,10 +603,10 @@ Current logger configuration:
         handler.</fsummary>
       <desc>
         <p>Add or update configuration data for the specified
-          handler. If the
-          given <c><anno>Key</anno></c> already exists, its associated
-          value will be set to <c><anno>Value</anno></c>. If it
-          doesn't exist, it will be added.</p>
+          handler. If the given <c><anno>Key</anno></c> already
+          exists, its associated value will be changed
+          to <c><anno>Value</anno></c>. If it doesn't exist, it will
+          be added.</p>
       </desc>
     </func>
 
@@ -471,30 +625,36 @@ Current logger configuration:
       <name name="set_process_metadata" arity="1"/>
       <fsummary>Set metadata to use when logging from current process.</fsummary>
       <desc>
-        <p>Set metadata which <c>logger</c> automatically inserts in
-          all log events produced on the current process. Subsequent
-          calls will overwrite previous data set by this function.</p>
-	<p>When logging, location data produced by the log macros,
-	  and/or metadata given as argument to the log call (API
-	  function or macro), will be merged with the process
-	  metadata. If the same keys occur, values from the metadata
-	  argument to the log call will overwrite values in the
-	  process metadata, which in turn will overwrite values from
-	  the location data.</p>
+        <p>Set metadata which Logger shall automatically insert in
+          all log events produced on the current process.</p>
+	<p>Location data produced by the log macros, and/or metadata
+	  given as argument to the log call (API function or macro),
+	  are merged with the process metadata. If the same keys
+	  occur, values from the metadata argument to the log call
+	  overwrite values from the process metadata, which in turn
+	  overwrite values from the location data.</p>
+	<p>Subsequent calls to this function overwrites previous data
+          set. To update existing data instead of overwriting it,
+          see <seealso marker="#update_process_metadata-1">
+	    <c>update_process_metadata/1</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name name="update_process_metadata" arity="1"/>
-      <fsummary>Update metadata to use when logging from current process.</fsummary>
+      <fsummary>Set or update metadata to use when logging from
+	current process.</fsummary>
       <desc>
-	<p>Update metadata to use when logging from current process</p>
-	<p>This function behaves as if it was implemented as follows:</p>
+	<p>Set or update metadata to use when logging from current
+	  process</p>
+	<p>If process metadata exists for the current process, this
+	  function behaves as if it was implemented as follows:</p>
 	<code type="erl">
 logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))
 	</code>
 	<p>If no process metadata exists, the function behaves as
-	  <seealso marker="#set_process_metadata-1"><c>set_process_metadata/1</c>
+	  <seealso marker="#set_process_metadata-1">
+	    <c>set_process_metadata/1</c>
 	  </seealso>.</p>
       </desc>
     </func>
@@ -505,7 +665,9 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))
       <desc>
         <p>Retrieve data set
           with <seealso marker="#set_process_metadata-1">
-	    <c>set_process_metadata/1</c></seealso>.</p>
+	    <c>set_process_metadata/1</c></seealso> or
+	  <seealso marker="#update_process_metadata-1">
+	    <c>update_process_metadata/1</c></seealso>.</p>
       </desc>
     </func>
 
@@ -515,12 +677,103 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta))
       <desc>
         <p>Delete data set
           with <seealso marker="#set_process_metadata-1">
-	    <c>set_process_metadata/1</c></seealso>.</p>
+	    <c>set_process_metadata/1</c></seealso> or
+	  <seealso marker="#update_process_metadata-1">
+	    <c>update_process_metadata/1</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="format_report" arity="1"/>
+      <fsummary>Convert a log message on report form to {Format,Args}.</fsummary>
+      <desc>
+        <p>Convert a log message on report form to <c>{Format,Args}</c>.</p>
+	<p>This is the default report callback used
+	  by <seealso marker="logger_formatter">
+	    <c>logger_formatter</c></seealso> when no custom report
+	    callback is found.</p>
+	<p>The function produces lines of <c>Key: Value</c> from
+	  key-value lists. Strings are printed with <c>~ts</c> and
+	  other terms with <c>~tp</c>.</p>
+	<p>If the <c><anno>Report</anno></c> is a map, it is
+	  converted to a key-value list before formatting as such.</p>
       </desc>
     </func>
 
   </funcs>
 
+  <section>
+    <title>Callback Functions</title>
+    <p>The following functions are to be exported from a handler
+      callback module.</p>
+  </section>
+
+  <funcs>
+    <func>
+      <name>Module:adding_handler(HandlerId,Config1) -> {ok,Config2} | {error,Reason}</name>
+      <fsummary>An instance of this handler is about to be added.</fsummary>
+      <type>
+	<v>HandlerId =
+	  <seealso marker="#type-handler_id">handler_id()</seealso></v>
+	<v>Config1 = Config2 =
+	  <seealso marker="#type-config">config()</seealso></v>
+	<v>Reason = term()</v>
+      </type>
+      <desc>
+	<p>This callback function is optional.</p>
+	<p>The function is called when an new handler is about to be
+	  added, and the purpose is to verify the configuration and
+	  initiate all resourced needed by the handler.</p>
+	<p>If everything succeeds, the callback function can add
+	  possible default values or internal state values to the
+	  configuration, and return the adjusted map
+	  in <c>{ok,Config2}</c>.</p>
+	<p>If the configuration is faulty, or if the initiation fails,
+	  the callback function must return <c>{error,Reason}</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:removing_handler(HandlerId,Config) -> ok</name>
+      <fsummary>The given handler is about to be removed.</fsummary>
+      <type>
+	<v>HandlerId =
+	  <seealso marker="#type-handler_id">handler_id()</seealso></v>
+	<v>Config =
+	  <seealso marker="#type-config">config()</seealso></v>
+      </type>
+      <desc>
+	<p>This callback function is optional.</p>
+	<p>The function is called when a handler is about to be
+	  removed, and the purpose is to release all resources used by
+	  the handler. The return value is ignored by Logger.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:changing_config(HandlerId,Config1,Config2) -> {ok,Config3} | {error,Reason}</name>
+      <fsummary>The configuration for this handler is about to change.</fsummary>
+      <type>
+	<v>HandlerId =
+	  <seealso marker="#type-handler_id">handler_id()</seealso></v>
+	<v>Config1 = Config2 = Config3 =
+	  <seealso marker="#type-config">config()</seealso></v>
+	<v>Reason = term()</v>
+      </type>
+      <desc>
+	<p>This callback function is optional.</p>
+	<p>The function is called when the configuration for a handler
+	  is about to change, and the purpose is to verify and act on
+	  the new configuration.</p>
+	<p><c>Config1</c> is the existing configuration
+	  and <c>Config2</c> is the new configuration.</p>
+	<p>If everything succeeds, the callback function must return a
+	  possibly adjusted configuration in <c>{ok,Config3}</c>.</p>
+	<p>If the configuration is faulty, the callback function must
+	  return <c>{error,Reason}</c>.</p>
+      </desc>
+    </func>
+  </funcs>
 </erlref>
 
 
diff --git a/lib/kernel/doc/src/logger_filters.xml b/lib/kernel/doc/src/logger_filters.xml
index d742391e35..c34ec7d14c 100644
--- a/lib/kernel/doc/src/logger_filters.xml
+++ b/lib/kernel/doc/src/logger_filters.xml
@@ -33,16 +33,20 @@
     <file>logger_filters.xml</file>
   </header>
   <module>logger_filters</module>
-  <modulesummary>Filters to use with logger.</modulesummary>
+  <modulesummary>Filters to use with Logger.</modulesummary>
 
   <description>
-    <p>Filters to use with logger. All functions exported from this
-      module can be used as logger or handler
+    <p>All functions exported from this module can be used as logger
+      or handler
       filters. See <seealso marker="logger#add_logger_filter-2">
 	<c>logger:add_logger_filter/2</c></seealso>
       and <seealso marker="logger#add_handler_filter-3">
-	<c>logger:add_handler_filter/3</c></seealso>
-      for more information about how filters are added.</p>
+	<c>logger:add_handler_filter/3</c></seealso> for more information
+      about how filters are added.</p>
+    <p>Filters are removed with <seealso marker="logger#remove_logger_filter-1">
+	<c>logger:remove_logger_filter/1</c></seealso>
+      and <seealso marker="logger#remove_handler_filter-2">
+	<c>logger:remove_handler_filter/2</c></seealso>.</p>
   </description>
 
   <funcs>
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>