[logger] Update documentation

1 files changed, 472 insertions, 411 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index 911eb158da..7f35a5d752 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -33,73 +33,150 @@
     <file>logger.xml</file>
   </header>
   <module>logger</module>
-  <modulesummary>API module for logging in Erlang/OTP.</modulesummary>
+  <modulesummary>API module for Logger, the standard logging facility
+    in Erlang/OTP.</modulesummary>
 
   <description>
-    <p>
-      This module is the main API for logging in Erlang/OTP. It
-      contains functions that allow applications to use a single log
-      API and the system to manage those log events independently. Use
-      the <seealso marker="#emergency-1">API functions</seealso> or the log
-      <seealso marker="#macros">macros</seealso> to log events. For instance,
-      to log a new error event:</p>
-      <code>
-?LOG_ERROR("error happened because: ~p",[Reason]). %% With macro
-logger:error("error happened because: ~p",[Reason]). %% Without macro
-      </code>
-      <p>This log event is then sent to the configured log handlers which
-      by default means that it is be printed to the console. If you want
-      your systems logs to be printed to a file instead of the console you
-      must configure the default handler to do so. The simplest way is
-      to include the following in your <seealso marker="config"><c>sys.config</c></seealso>.</p>
+    <p>This module implements the main API for logging in
+      Erlang/OTP. To create a log event, use the
+      <seealso marker="#logging_API">API functions</seealso> or the
+      log
+      <seealso marker="#macros">macros</seealso>, for example:</p>
+    <code>
+?LOG_ERROR("error happened because: ~p", [Reason]).   % With macro
+logger:error("error happened because: ~p", [Reason]). % Without macro
+    </code>
+    <p>To configure the Logger backend,
+      use <seealso marker="kernel_app#logger">Kernel configuration
+      parameters</seealso>
+      or <seealso marker="#configuration_API">configuration
+      functions</seealso> in the Logger API.</p>
+
+    <p>By default, the Kernel application installs one log handler at
+      system start. This handler is named <c>default</c>. It receives
+      and processes standard log events produced by the Erlang runtime
+      system, standard behaviours and different Erlang/OTP
+      applications. The log events are by default printed to the
+      terminal.</p>
+    <p>If you want your systems logs to be printed to a file instead,
+      you must configure the default handler to do so. The simplest
+      way is to include the following in
+      your <seealso marker="config"><c>sys.config</c></seealso>:</p>
       <code>
 [{kernel,
   [{logger,
-    [{handler,default,logger_std_h,
-      #{logger_std_h=>#{type=>{file,"path/to/file.log"}}}}]}]}].
+    [{handler, default, logger_std_h,
+      #{config => #{type => {file, "path/to/file.log"}}}}]}]}].
       </code>
     <p>
       For more information about:
     </p>
     <list type="bulleted">
-      <item>how to use the API,
-        see <seealso marker="logger_chapter">the User's Guide</seealso>.</item>
-      <item>how to configure Logger,
-        see the <seealso marker="logger_chapter#configuration">Configuration</seealso>
+      <item>the Logger facility in general, see
+        the <seealso marker="logger_chapter">User's
+        Guide</seealso>.</item>
+      <item>how to configure Logger, see
+        the <seealso marker="logger_chapter#configuration">Configuration</seealso>
         section in the User's Guide.</item>
-      <item>the convinience macros in logger.hrl,
-        see <seealso marker="#macros">the macro section</seealso>.</item>
-      <item>what the builtin formatter can do,
-        see <seealso marker="logger_formatter">logger_formatter</seealso>.</item>
-      <item>what the builtin handlers can do,
+      <item>the built-in handlers,
         see <seealso marker="logger_std_h">logger_std_h</seealso> and
         <seealso marker="logger_disk_log_h">logger_disk_log_h</seealso>.</item>
-      <item>what builtin filters are available,
+      <item>the built-in formatter,
+        see <seealso marker="logger_formatter">logger_formatter</seealso>.</item>
+      <item>built-in filters,
       see <seealso marker="logger_filters">logger_filters</seealso>.</item>
     </list>
   </description>
 
   <datatypes>
     <datatype>
-      <name name="level"/>
+      <name name="primary_config"/>
       <desc>
-	<p>The severity level for the message to be logged.</p>
+	<p>Primary configuration data for Logger. 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>
+	</list>
       </desc>
     </datatype>
     <datatype>
-      <name name="log_event"/>
+      <name name="handler_config"/>
       <desc>
-	<p></p>
+	<p>Handler configuration data for Logger. The following
+	  default values apply:</p>
+	<list>
+	  <item><c>level => all</c></item>
+	  <item><c>filter_default => log</c></item>
+	  <item><c>filters => []</c></item>
+	  <item><c>formatter => {logger_formatter, DefaultFormatterConfig</c>}</item>
+	</list>
+	<p>In addition to these, the following fields are
+	  automatically inserted by Logger, values taken from the
+	  two first parameters
+	  to <seealso marker="#add_handler-3"><c>add_handler/3</c></seealso>:</p>
+	<list>
+	  <item><c>id => HandlerId</c></item>
+	  <item><c>module => Module</c></item>
+	</list>
+	<p>Handler specific configuration data is inserted by the
+	  handler callback itself, in a sub structure associated with
+	  the field named <c>config</c>.</p>
+	<p>See the <seealso marker="logger_formatter#type-config">
+	    <c>logger_formatter(3)</c></seealso> manual page for
+	  information about the default configuration for this
+	  formatter.</p>
       </desc>
     </datatype>
     <datatype>
-      <name name="report"/>
+      <name name="filter"/>
       <desc>
-	<p></p>
+	<p>A filter which can be installed as a handler filter, or as
+	  a primary filter in Logger.</p>
       </desc>
     </datatype>
     <datatype>
-      <name name="msg_fun"/>
+      <name name="filter_arg"/>
+      <desc>
+	<p>The second argument to the filter fun.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="filter_id"/>
+      <desc>
+	<p>A unique identifier for a filter.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="filter_return"/>
+      <desc>
+	<p>The return value from the filter fun.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="formatter_config"/>
+      <desc>
+	<p>Configuration data for the
+	formatter. See <seealso marker="logger_formatter">
+	    <c>logger_formatter(3)</c></seealso>
+	  for an example of a formatter implementation.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="handler_id"/>
+      <desc>
+	<p>A unique identifier for a handler instance.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="level"/>
+      <desc>
+	<p>The severity level for the message to be logged.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="log_event"/>
       <desc>
 	<p></p>
       </desc>
@@ -117,7 +194,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
 	<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>mfa  => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY}</c></item>
 	  <item><c>file => ?FILE</c></item>
 	  <item><c>line => ?LINE</c></item>
 	</list>
@@ -158,51 +235,15 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
       </desc>
     </datatype>
     <datatype>
-      <name name="config"/>
-      <desc>
-	<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#type-config">
-	    <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>A unique identifier for a handler instance.</p>
-      </desc>
-    </datatype>
-    <datatype>
-      <name name="filter_id"/>
-      <desc>
-	<p>A unique identifier for a filter.</p>
-      </desc>
-    </datatype>
-    <datatype>
-      <name name="filter"/>
-      <desc>
-	<p>A filter which can be installed for the logger part of
-	  Logger, or for a handler.</p>
-      </desc>
-    </datatype>
-    <datatype>
-      <name name="filter_arg"/>
+      <name name="msg_fun"/>
       <desc>
-	<p>The second argument to the filter fun.</p>
+	<p></p>
       </desc>
     </datatype>
     <datatype>
-      <name name="filter_return"/>
+      <name name="report"/>
       <desc>
-	<p>The return value from the filter fun.</p>
+	<p></p>
       </desc>
     </datatype>
     <datatype>
@@ -213,15 +254,6 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
 	    <c>erlang:system_time(microsecond)</c></seealso>.</p>
       </desc>
     </datatype>
-    <datatype>
-      <name name="formatter_config"/>
-      <desc>
-	<p>Configuration data for the
-	formatter. See <seealso marker="logger_formatter">
-	    <c>logger_formatter(3)</c></seealso>
-	  for an example of a formatter implementation.</p>
-      </desc>
-    </datatype>
   </datatypes>
 
   <section>
@@ -258,6 +290,10 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
       level.</p>
   </section>
 
+  <section>
+    <marker id="logging_API"/>
+    <title>Logging API functions</title>
+  </section>
   <funcs>
     <func>
       <name>emergency(StringOrReport[,Metadata])</name>
@@ -317,7 +353,7 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
     <func>
       <name>notice(StringOrReport[,Metadata])</name>
       <name>notice(Format,Args[,Metadata])</name>
-      <name>notice(Fun,FunArgs[,Metadata])</name>
+     <name>notice(Fun,FunArgs[,Metadata])</name>
       <fsummary>Logs the given message as level <c>notice</c>.</fsummary>
       <desc>
         <p>Equivalent to
@@ -366,136 +402,21 @@ logger:error("error happened because: ~p",[Reason]). %% Without macro
         <p>Log the given message.</p>
       </desc>
     </func>
+  </funcs>
 
+  <section>
+    <marker id="configuration_API"/>
+    <title>Configuration API functions</title>
+  </section>
+  <funcs>
     <func>
-      <name name="get_logger_config" arity="0"/>
-      <fsummary>Look up the current configuration for the logger part
-	of Logger.</fsummary>
-      <desc>
-        <p>Look up the current configuration for the logger part of
-          Logger.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name name="get_handler_config" arity="1"/>
-      <fsummary>Look up the current configuration for the given
-	handler.</fsummary>
-      <desc>
-        <p>Look up the current configuration for the given handler.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name name="i" arity="0"/>
-      <fsummary>Get all Logger configurations</fsummary>
-      <desc>
-        <p>Same as <seealso marker="#i/1"><c>logger:i(term)</c></seealso></p>
-      </desc>
-    </func>
-
-    <func>
-      <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 all Logger configurations</fsummary>
-      <desc>
-        <p>Display or return all current Logger configurations.</p>
-        <taglist>
-          <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 between 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">
-	      <c>logger:get_logger_config/0</c></seealso>.</p>
-            <p>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
-  Filter Default: log
-  Filters:
-  Handlers:
-    Id: default
-      Module:    logger_std_h
-      Level:     info
-      Formatter:
-        Module: logger_formatter
-        Config: #{legacy_header => true,single_line => false,
-                  template => [{logger_formatter,header},"\n",msg,"\n"]}
-      Filter Default: stop
-      Filters:
-        Id: stop_progress
-          Fun:    fun logger_filters:progress/2
-          Config: stop
-        Id: remote_gl
-          Fun:    fun logger_filters:remote_gl/2
-          Config: stop
-        Id: domain
-          Fun:    fun logger_filters:domain/2
-          Config: {log,super,[beam,erlang,otp,sasl]}
-        Id: no_domain
-          Fun:    fun logger_filters:domain/2
-          Config: {log,undefined,[]}
-      Handler Config:
-        logger_std_h: #{type => standard_io}
-  Level set per module:
-    Module: my_module
-      Level:    debug]]></code>
-          </item>
-        </taglist>
-      </desc>
-    </func>
-
-    <func>
-      <name name="add_logger_filter" arity="2"/>
-      <fsummary>Add a filter to the logger part of Logger.</fsummary>
+      <name name="add_handler" arity="3"/>
+      <fsummary>Add a handler with the given configuration.</fsummary>
       <desc>
-        <p>Add a filter to the logger part of 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_event()</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 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 part specifies if
-	      the log event shall be discarded or forwarded to the
-	      handler part.</p>
-	  </item>
-	</taglist>
-	<p>See section <seealso marker="logger_chapter#filters">
-	    Filters</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>
+        <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 referring to this
+	  handler.</p>
       </desc>
     </func>
 
@@ -541,98 +462,12 @@ Current logger configuration:
     </func>
 
     <func>
-      <name name="remove_logger_filter" arity="1"/>
-      <fsummary>Remove a filter from the logger part of Logger.</fsummary>
-      <desc>
-        <p>Remove the filter identified
-          by <c><anno>FilterId</anno></c> from the logger part of Logger.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name name="remove_handler_filter" arity="2"/>
-      <fsummary>Remove a filter from the specified handler.</fsummary>
-      <desc>
-        <p>Remove the filter identified
-          by <c><anno>FilterId</anno></c> from the handler identified
-          by <c><anno>HandlerId</anno></c>.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name name="add_handler" arity="3"/>
-      <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 referring to this
-	  handler.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name name="remove_handler" arity="1"/>
-      <fsummary>Remove the handler with the specified identity.</fsummary>
-      <desc>
-        <p>Remove the handler identified by <c><anno>HandlerId</anno></c>.</p>
-      </desc>
-    </func>
-
-    <func>
-      <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 <c><anno>Module</anno></c>.</p>
-	<p>The log level for a module overrides the global log level
-	  of Logger for log events 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 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 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 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 an API function
-	    is called directly, without using a macro, the logging
-	    client must explicitly add this information if module
-	    levels shall have any effect.</p>
-	</note>
-      </desc>
-    </func>
-
-    <func>
-      <name name="unset_module_level" arity="1"/>
-      <fsummary>Remove a module specific log setting.</fsummary>
-      <desc>
-        <p>Remove a module specific log setting. After this, the
-          global log level is used for the specified module.</p>
-      </desc>
-    </func>
-
-    <func>
       <name name="add_handlers" arity="1" clause_i="1"/>
       <fsummary>Set up log handlers from the application's
 	configuration parameters.</fsummary>
       <desc>
         <p>Reads the application configuration parameter <c>logger</c> and
-          calls <c>logger:add_handlers/1</c> with its contents.</p>
+          calls <c>add_handlers/1</c> with its contents.</p>
       </desc>
     </func>
 
@@ -670,61 +505,158 @@ start(_, []) ->
 [{kernel,
   [{logger,
     %% Disable the default Kernel handler
-    [{handler,default,undefined}]}]},
+    [{handler, default, undefined}]}]},
  {my_app,
   [{logger,
     %% Enable this handler as the default
-    [{handler,default,my_handler,#{}}]}]}].
+    [{handler, default, my_handler, #{}}]}]}].
          </code>
       </desc>
     </func>
 
     <func>
-      <name name="set_logger_config" arity="1"/>
-      <fsummary>Set configuration data for the logger part of Logger.</fsummary>
+      <name name="add_primary_filter" arity="2"/>
+      <fsummary>Add a primary filter to Logger.</fsummary>
       <desc>
-        <p>Set configuration data for the logger part of Logger. This
-          overwrites the current logger configuration.</p>
-	<p>To modify the existing configuration,
-	  use <seealso marker="#update_logger_config-1">
-	    <c>update_logger_config/1</c></seealso>, or, if a more
-	  complex merge is needed, read the current configuration
-	  with <seealso marker="#get_logger_config-0"><c>get_logger_config/0</c>
-	  </seealso>, then do the merge before writing the new
-	  configuration back with this function.</p>
-	<p>If a key is removed compared to the current configuration,
-	  the default value is used.</p>
+        <p>Add a primary filter to 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_event()</c></tag>
+	  <item>
+	    <p>The filter <em>passed</em>. The next primary filter, if
+	      any, is applied. If no more primary filters exist, the
+	      log event is forwarded to the handler part of 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
+	      primary filter, if any, is applied. If no more primary
+	      filters exist, the value of the
+	      primary <c>filter_default</c> configuration parameter
+	      specifies if the log event shall be discarded or
+	      forwarded to the handler part.</p>
+	  </item>
+	</taglist>
+	<p>See section <seealso marker="logger_chapter#filters">
+	    Filters</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>
 
     <func>
-      <name name="set_logger_config" arity="2"/>
-      <fsummary>Add or update configuration data for the logger part
-	of Logger.</fsummary>
+      <name name="get_config" arity="0"/>
+      <fsummary>Look up the current Logger configuration</fsummary>
       <desc>
-        <p>Add or update configuration data for the logger part of
-          Logger. If the given <c><anno>Key</anno></c> already exists,
-          its associated value will be changed
-          to <c><anno>Value</anno></c>. If it does not exist, it will
-          be added.</p>
+        <p>Look up all current Logger configuration, including primary
+          and handler configuration, and module level settings.</p>
       </desc>
     </func>
 
     <func>
-      <name name="update_logger_config" arity="1"/>
-      <fsummary>Update configuration data for the logger part of
-	Logger.</fsummary>
+      <name name="get_handler_config" arity="0"/>
+      <fsummary>Look up the current configuration for all handlers.</fsummary>
       <desc>
-        <p>Update configuration data for the logger part of
-          Logger. This function behaves as if it was implemented as
-          follows:</p>
-	<code type="erl">
-{ok,Old} = logger:get_logger_config(),
-logger:set_logger_config(maps:merge(Old,Config)).
-	</code>
-	<p>To overwrite the existing configuration without any merge,
-	  use <seealso marker="#set_logger_config-1"><c>set_logger_config/1</c>
-	  </seealso>.</p>
+        <p>Look up the current configuration for all handlers.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_handler_config" arity="1"/>
+      <fsummary>Look up the current configuration for the given
+	handler.</fsummary>
+      <desc>
+        <p>Look up the current configuration for the given handler.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_handler_ids" arity="0"/>
+      <fsummary>Look up the identities for all installed handlers.</fsummary>
+      <desc>
+        <p>Look up the identities for all installed handlers.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_primary_config" arity="0"/>
+      <fsummary>Look up the current primary configuration for Logger.</fsummary>
+      <desc>
+        <p>Look up the current primary configuration for Logger.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_module_level" arity="0"/>
+      <fsummary>Look up all current module levels.</fsummary>
+      <desc>
+        <p>Look up all current module levels. Returns a list
+          containing one <c>{Module,Level}</c> element for each module
+          for which the module level was previously set
+          with <seealso marker="#set_module_level-2">
+	    <c>set_module_level/2</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_module_level" arity="1"/>
+      <fsummary>Look up the current level for the given modules.</fsummary>
+      <desc>
+        <p>Look up the current level for the given modules. Returns a
+          list containing one <c>{Module,Level}</c> element for each
+          of the given modules for which the module level was
+          previously set with <seealso marker="#set_module_level-2">
+	    <c>set_module_level/2</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="get_process_metadata" arity="0"/>
+      <fsummary>Retrieve data set with set_process_metadata/1.</fsummary>
+      <desc>
+        <p>Retrieve data set
+          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>
+      </desc>
+    </func>
+
+    <func>
+      <name name="remove_handler" arity="1"/>
+      <fsummary>Remove the handler with the specified identity.</fsummary>
+      <desc>
+        <p>Remove the handler identified by <c><anno>HandlerId</anno></c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="remove_handler_filter" arity="2"/>
+      <fsummary>Remove a filter from the specified handler.</fsummary>
+      <desc>
+        <p>Remove the filter identified
+          by <c><anno>FilterId</anno></c> from the handler identified
+          by <c><anno>HandlerId</anno></c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="remove_primary_filter" arity="1"/>
+      <fsummary>Remove a primary filter from Logger.</fsummary>
+      <desc>
+        <p>Remove the primary filter identified
+          by <c><anno>FilterId</anno></c> from Logger.</p>
       </desc>
     </func>
 
@@ -763,18 +695,122 @@ logger:set_logger_config(maps:merge(Old,Config)).
     </func>
 
     <func>
-      <name name="update_handler_config" arity="2"/>
-      <fsummary>Update configuration data for the specified handler.</fsummary>
+      <name name="set_primary_config" arity="1"/>
+      <fsummary>Set primary configuration data for Logger.</fsummary>
       <desc>
-        <p>Update configuration data for the specified handler. This function
-          behaves as if it was implemented as follows:</p>
-	<code type="erl">
-{ok,{_,Old}} = logger:get_handler_config(HandlerId),
-logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
-	</code>
-	<p>To overwrite the existing configuration without any merge,
-	  use <seealso marker="#set_handler_config-2"><c>set_handler_config/2</c>
+        <p>Set primary configuration data for Logger. This
+          overwrites the current configuration.</p>
+	<p>To modify the existing configuration,
+	  use <seealso marker="#update_primary_config-1">
+	    <c>update_primary_config/1</c></seealso>, or, if a more
+	  complex merge is needed, read the current configuration
+	  with <seealso marker="#get_primary_config-0"><c>get_primary_config/0</c>
+	  </seealso>, then do the merge before writing the new
+	  configuration back with this function.</p>
+	<p>If a key is removed compared to the current configuration,
+	  the default value is used.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_primary_config" arity="2"/>
+      <fsummary>Add or update primary configuration data for Logger.</fsummary>
+      <desc>
+        <p>Add or update primary configuration data for Logger. If the
+          given <c><anno>Key</anno></c> already exists, its associated
+          value will be changed to <c><anno>Value</anno></c>. If it
+          does not exist, it will be added.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_module_level" arity="2"/>
+      <fsummary>Set the log level for the specified modules.</fsummary>
+      <desc>
+        <p>Set the log level for the
+          specified modules.</p>
+	<p>The log level for a module overrides the primary log level
+	  of Logger for log events 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 primary log level for 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 primary log level.</p>
+	<p>If the level for <c>mymodule</c> is 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 primary log level for Logger, use
+          <seealso marker="#set_primary_config/2">
+	    <c>set_primary_config(level, Level)</c></seealso>.</p>
+        <p>To change the log level for a handler, use
+          <seealso marker="#set_handler_config/3">
+	    <c>set_handler_config(HandlerId, level, Level)</c>
 	  </seealso>.</p>
+	<note>
+	  <p>The originating module for a log event is only detected
+	    if the key <c>mfa</c> exists in the metadata, and is
+	    associated with <c>{Module, Function, Arity}</c>. When log
+	    macros are used, this association is automatically added
+	    to all log events. If an API function is called directly,
+	    without using a macro, the logging client must explicitly
+	    add this information if module levels shall have any
+	    effect.</p>
+	</note>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_process_metadata" arity="1"/>
+      <fsummary>Set metadata to use when logging from current process.</fsummary>
+      <desc>
+        <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="unset_module_level" arity="0"/>
+      <fsummary>Remove module specific log settings for all modules.</fsummary>
+      <desc>
+        <p>Remove module specific log settings. After this, the
+          primary log level is used for all modules.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="unset_module_level" arity="1"/>
+      <fsummary>Remove module specific log settings for the given
+	modules.</fsummary>
+      <desc>
+        <p>Remove module specific log settings. After this, the
+          primary log level is used for the specified modules.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="unset_process_metadata" arity="0"/>
+      <fsummary>Delete data set with set_process_metadata/1.</fsummary>
+      <desc>
+        <p>Delete data set
+          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>
       </desc>
     </func>
 
@@ -786,9 +822,10 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
 	<p>The new configuration is merged with the existing formatter
 	  configuration.</p>
 	<p>To overwrite the existing configuration without any merge,
-	  use <seealso marker="#set_handler_config-3">
-	    <c>set_handler_config(HandlerId,formatter,
-	      {FormatterModule,FormatterConfig})</c></seealso>.</p>
+	  use</p>
+	<pre>
+<seealso marker="#set_handler_config-3">set_handler_config(HandlerId, formatter,
+	      {FormatterModule, FormatterConfig})</seealso>.</pre>
       </desc>
     </func>
 
@@ -797,39 +834,41 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
       <fsummary>Update the formatter configuration for the specified handler.</fsummary>
       <desc>
         <p>Update the formatter configuration for the specified handler.</p>
-	<p>This is equivalent
-	  to <br/><seealso marker="#update_formatter_config-2">
-	    <c>update_formatter_config(<anno>HandlerId</anno>,#{<anno>Key</anno>=><anno>Value</anno>})</c></seealso></p>
+	<p>This is equivalent to</p>
+	<pre>
+<seealso marker="#update_formatter_config-2">update_formatter_config(<anno>HandlerId</anno>, #{<anno>Key</anno> => <anno>Value</anno>})</seealso></pre>
       </desc>
     </func>
 
     <func>
-      <name name="compare_levels" arity="2"/>
-      <fsummary>Compare the severity of two log levels.</fsummary>
+      <name name="update_handler_config" arity="2"/>
+      <fsummary>Update configuration data for the specified handler.</fsummary>
       <desc>
-        <p>Compare the severity of two log levels. Returns <c>gt</c>
-          if <c>Level1</c> is more severe than
-          <c>Level2</c>, <c>lt</c> if <c>Level1</c> is less severe,
-          and <c>eq</c> if the levels are equal.</p>
+        <p>Update configuration data for the specified handler. This function
+          behaves as if it was implemented as follows:</p>
+	<code type="erl">
+{ok, {_, Old}} = logger:get_handler_config(HandlerId),
+logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
+	</code>
+	<p>To overwrite the existing configuration without any merge,
+	  use <seealso marker="#set_handler_config-2"><c>set_handler_config/2</c>
+	  </seealso>.</p>
       </desc>
     </func>
 
     <func>
-      <name name="set_process_metadata" arity="1"/>
-      <fsummary>Set metadata to use when logging from current process.</fsummary>
+      <name name="update_primary_config" arity="1"/>
+      <fsummary>Update primary configuration data for Logger.</fsummary>
       <desc>
-        <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>
+        <p>Update primary configuration data for Logger. This function
+          behaves as if it was implemented as follows:</p>
+	<code type="erl">
+Old = logger:get_primary_config(),
+logger:set_primary_config(maps:merge(Old, Config)).
+	</code>
+	<p>To overwrite the existing configuration without any merge,
+	  use <seealso marker="#set_primary_config-1"><c>set_primary_config/1</c>
+	  </seealso>.</p>
       </desc>
     </func>
 
@@ -843,7 +882,7 @@ logger:set_handler_config(HandlerId,maps:merge(Old,Config)).
 	<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)).
+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">
@@ -851,48 +890,44 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
 	  </seealso>.</p>
       </desc>
     </func>
+  </funcs>
 
+  <section>
+    <marker id="misc_API"/>
+    <title>Miscellaneous API functions</title>
+  </section>
+  <funcs>
     <func>
-      <name name="get_process_metadata" arity="0"/>
-      <fsummary>Retrieve data set with set_process_metadata/1.</fsummary>
-      <desc>
-        <p>Retrieve data set
-          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>
-      </desc>
-    </func>
-
-    <func>
-      <name name="unset_process_metadata" arity="0"/>
-      <fsummary>Delete data set with set_process_metadata/1.</fsummary>
+      <name name="compare_levels" arity="2"/>
+      <fsummary>Compare the severity of two log levels.</fsummary>
       <desc>
-        <p>Delete data set
-          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>Compare the severity of two log levels. Returns <c>gt</c>
+          if <c>Level1</c> is more severe than
+          <c>Level2</c>, <c>lt</c> if <c>Level1</c> is less severe,
+          and <c>eq</c> if the levels are equal.</p>
       </desc>
     </func>
 
     <func>
       <name name="format_report" arity="1"/>
-      <fsummary>Convert a log message on report form to {Format,Args}.</fsummary>
+      <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
+        <p>Convert a log message on report form to <c>{Format,
+	  Args}</c>. 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>
+	  callback is found. See
+	  section <seealso marker="logger_chapter#log_message">Log
+	    Message</seealso> in the Kernel User's Guide for
+	  information about report callbacks and valid forms of log
+	  messages.</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>
+	<p>If <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>
@@ -904,11 +939,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
 
   <funcs>
     <func>
-      <name>HModule:adding_handler(Config1) -> {ok,Config2} | {error,Reason}</name>
+      <name>HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}</name>
       <fsummary>An instance of this handler is about to be added.</fsummary>
       <type>
 	<v>Config1 = Config2 =
-	  <seealso marker="#type-config">config()</seealso></v>
+	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
 	<v>Reason = term()</v>
       </type>
       <desc>
@@ -928,11 +963,11 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
     </func>
 
     <func>
-      <name>HModule:changing_config(Config1,Config2) -> {ok,Config3} | {error,Reason}</name>
+      <name>HModule:changing_config(Config1, Config2) -> {ok, Config3} | {error, Reason}</name>
       <fsummary>The configuration for this handler is about to change.</fsummary>
       <type>
 	<v>Config1 = Config2 = Config3 =
-	  <seealso marker="#type-config">config()</seealso></v>
+	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
 	<v>Reason = term()</v>
       </type>
       <desc>
@@ -952,17 +987,17 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
     </func>
 
     <func>
-      <name>HModule:log(LogEvent,Config) -> void()</name>
+      <name>HModule:log(LogEvent, Config) -> void()</name>
       <fsummary>Log the given log event.</fsummary>
       <type>
 	<v>LogEvent =
 	  <seealso marker="#type-log_event">log_event()</seealso></v>
 	<v>Config =
-	  <seealso marker="#type-config">config()</seealso></v>
+	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
       </type>
       <desc>
 	<p>This callback function is mandatory.</p>
-	<p>The function is called when all global filters and all
+	<p>The function is called when all primary filters and all
 	  handler filters for the handler in question have passed for
 	  the given log event.</p>
 	<p>The handler identity is associated with the <c>id</c> key
@@ -978,7 +1013,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
       <fsummary>The given handler is about to be removed.</fsummary>
       <type>
 	<v>Config =
-	  <seealso marker="#type-config">config()</seealso></v>
+	  <seealso marker="#type-handler_config">handler_config()</seealso></v>
       </type>
       <desc>
 	<p>This callback function is optional.</p>
@@ -1002,18 +1037,30 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
 
   <funcs>
     <func>
-      <name>FModule:check_config(FConfig) -> ok | {error,term()}</name>
+      <name>FModule:check_config(FConfig) -> ok | {error, Reason}</name>
       <fsummary>Validate the given formatter configuration.</fsummary>
       <type>
 	<v>FConfig =
 	  <seealso marker="#type-formatter_config">formatter_config()</seealso></v>
+	<v>Reason = term()</v>
       </type>
       <desc>
 	<p>This callback function is optional.</p>
 	<p>The function is called by a Logger when formatter
 	  configuration is set or modified. The formatter must
 	  validate the given configuration and return <c>ok</c> if it
-	  is correct, and <c>{error,term()}</c> if it is faulty.</p>
+	  is correct, and <c>{error,Reason}</c> if it is faulty.</p>
+	<p>The following Logger API functions can trigger this callback:</p>
+	<list>
+	  <item><seealso marker="logger#add_handler-3">
+	      <c>logger:add_handler/3</c></seealso></item>
+	  <item><seealso marker="logger#set_handler_config-2">
+	      <c>logger:set_handler_config/2,3</c></seealso></item>
+	  <item><seealso marker="logger#update_handler_config-2">
+	      <c>logger:updata_handler_config/2</c></seealso></item>
+	  <item><seealso marker="logger#update_formatter_config-2">
+	      <c>logger:update_formatter_config/2</c></seealso></item>
+	</list>
 	<p>See <seealso marker="logger_formatter">
 	    <c>logger_formatter(3)</c></seealso>
 	  for an example implementation. <c>logger_formatter</c> is the
@@ -1021,7 +1068,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
       </desc>
     </func>
     <func>
-      <name>FModule:format(LogEvent,FConfig) -> FormattedLogEntry</name>
+      <name>FModule:format(LogEvent, FConfig) -> FormattedLogEntry</name>
       <fsummary>Format the given log event.</fsummary>
       <type>
 	<v>LogEvent =
@@ -1045,6 +1092,20 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(),Meta)).
       </desc>
     </func>
   </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p>
+      <seealso marker="config"><c>config(4)</c></seealso>,
+      <seealso marker="erts:erlang"><c>erlang(3)</c></seealso>,
+      <seealso marker="stdlib:io"><c>io(3)</c></seealso>,
+      <seealso marker="logger_disk_log_h"><c>logger_disk_log_h(3)</c></seealso>,
+      <seealso marker="logger_filters"><c>logger_filters(3)</c></seealso>,
+      <seealso marker="logger_formatter"><c>logger_formatter(3)</c></seealso>,
+      <seealso marker="logger_std_h"><c>logger_std_h(3)</c></seealso>,
+      <seealso marker="stdlib:unicode"><c>unicode(3)</c></seealso>
+    </p>
+  </section>
 </erlref>