logger: Rework configuration of logger

Most logger configuration that was possible through
kernel application variables have been moved into a
common 'logger' application environment in kernel.

Now all the configuration possible through the logger
API can be done as sys config.

The handler started by kernel has been renamed to 'default'
instead of logger_std_h.

There is a new logger:setup_handlers/1 function that given an
application name can be used to setup handlers in other applications.

1 files changed, 96 insertions, 7 deletions

diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml
index d901454e62..239b9553b1 100644
--- a/lib/kernel/doc/src/logger.xml
+++ b/lib/kernel/doc/src/logger.xml
@@ -33,10 +33,49 @@
     <file>logger.xml</file>
   </header>
   <module>logger</module>
-  <modulesummary>API module for the logger application.</modulesummary>
+  <modulesummary>API module for the logger.</modulesummary>
 
   <description>
-
+    <p>
+      This module is the main logger API. It contains functions that allow
+      application to use a single log API and the system to manage those log
+      events independently. To log events the logger
+      <seealso marker="#macros">macros</seealso> should be used. For instance,
+      to log a new error log 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 will then be sent to the configured log handlers which
+      by default means that it will be printed to the console. If you want
+      your systems logs to be printed to a file instead of the console you
+      have to 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"}}}}]}]}].
+      </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>
+        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,
+        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,
+      see <seealso marker="logger_filters">logger_filters</seealso>.</item>
+    </list>
   </description>
 
   <datatypes>
@@ -348,16 +387,16 @@
             <code><![CDATA[1> logger:i(print).
 Current logger configuration:
   Level: info
-  FilterDefault: log
+  Filter Default: log
   Filters:
   Handlers:
-    Id: logger_std_h
+    Id: default
       Module:    logger_std_h
       Level:     info
       Formatter:
         Module: logger_formatter
-        Config: #{template => [{logger_formatter,header},"\n",msg,"\n"],
-                  legacy_header => true}
+        Config: #{legacy_header => true,single_line => false,
+                  template => [{logger_formatter,header},"\n",msg,"\n"]}
       Filter Default: stop
       Filters:
         Id: stop_progress
@@ -550,6 +589,56 @@ Current logger configuration:
     </func>
 
     <func>
+      <name name="add_handlers" arity="1" clause_i="1"/>
+      <fsummary>Setup logger handlers from the applications configuration parameters.</fsummary>
+      <desc>
+        <p>Reads the application configuration parameter <c>logger</c> and
+          calls <c>logger:add_handlers/1</c> with it contents.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="add_handlers" arity="1" clause_i="2"/>
+      <fsummary>Setup logger handlers.</fsummary>
+      <type name="config_handler"/>
+      <desc>
+        <p>This function should be used by custom logger handlers to make
+        configuration consistent no matter which handler the system uses.
+        Normal usage to to add a call to <c>logger:add_handlers/1</c>
+        just after the processes that the handler needs are started
+        and pass the applications logger config as an argument. Eg.</p>
+        <code>
+-behaviour(application).
+start(_, []) ->
+    case supervisor:start_link({local, my_sup}, my_sup, []) of
+        {ok, Pid} ->
+            ok = logger:add_handlers(my_app),
+            {ok, Pid, []};
+        Error -> Error
+     end.</code>
+       <p>This will read the <c>logger</c> configuration parameter from
+         the handler application and start the configured handlers. The contents
+         of the configuration use the same rules as the
+         <seealso marker="logger_chapter#handler-configuration">logger handler configuration</seealso>.
+       </p>
+       <p>If the handler is meant to replace the default handler the kernels
+         default handlers have to be disabled before the new handler is added.
+         A <c>sys.config</c> file that disables the kernel handler and adds
+         a custom handler could looks like this:</p>
+         <code>
+[{kernel,
+  [{logger,
+    %% Disable the default kernel handler
+    [{handler,default,undefined}]}]},
+ {my_app,
+  [{logger,
+    %% Enable this handler as the default
+    [{handler,default,my_handler,#{}}]}]}].
+         </code>
+      </desc>
+    </func>
+
+    <func>
       <name name="set_logger_config" arity="1"/>
       <fsummary>Set configuration data for the logger.</fsummary>
       <desc>
@@ -650,7 +739,7 @@ Current logger configuration:
 	<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">