Add documentation of the built-in logger handlers

1 files changed, 81 insertions, 29 deletions

diff --git a/lib/kernel/doc/src/logger_std_h.xml b/lib/kernel/doc/src/logger_std_h.xml
index 2a368b16eb..fe9b9ca5a9 100644
--- a/lib/kernel/doc/src/logger_std_h.xml
+++ b/lib/kernel/doc/src/logger_std_h.xml
@@ -39,42 +39,94 @@
     <p>This is the default handler for the Logger
       application. Multiple instances of this handler can be added to
       logger, and each instance will print logs to <c>standard_io</c>,
-      <c>standard_error</c> or to a file.</p>
-
-    <p>To add a new instance,
-      use <seealso marker="logger#add_handler-3"><c>logger:add_handler/3</c>
+      <c>standard_error</c> or to file. The default instance that starts
+      with kernel is named <c>logger_std_h</c> - which is the name to be used
+      for reconfiguration.</p>
+    <p>The handler has an overload protection mechanism that will keep the handler
+      process and the kernel application alive during a high load of log 
+      requests. How this feature works, and how to modify the configuration,
+      is described in the
+      <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c>
       </seealso>.</p>
-
-    <p>The handler configuration may contain the following keys,
-      associated with values as described:</p>
+    <p>To add a new instance of the standard handler, use
+      <seealso marker="logger#add_handler-3"><c>logger:add_handler/3</c>
+      </seealso>. The handler configuration argument is a map which may contain
+       general configuration parameters, as documented in the
+       <seealso marker="logger_chapter#handler_configuration"><c>User's Guide</c>
+       </seealso>, as well as handler specific parameters. The specific parameters
+       are stored in a sub map with the key <c>logger_std_h</c>. The following
+       keys and values may be specified:</p>
     <taglist>
-      <tag><c>filters</c></tag>
-      <item>
-	<p>A list of <c>{Id,{Fun,Args}}</c>, each representing a filter
-	  that may selct or modify log events to forward to this
-	  handler.</p></item>
-      <tag><c>filter_default</c></tag>
-      <item>
-	<p>The atom <c>log</c> or <c>stop</c>, specifying what to
-	  do with a log event if all filters
-	  return <c>ignore</c>.</p></item>
-      <tag><c>formatter</c></tag>
+      <tag><c>type</c></tag>
       <item>
-	<p><c>{Module,Extra}</c>,
-	  where <c>Module:format(Log,Extra)</c> will be called by
-	  the handler to produce the string that will be printed to
-	  the handler's destination.</p></item>
-      <tag><c>level</c></tag>
+	<p>This will have the value <c>standard_io</c>, <c>standard_error</c>,
+	<c>{file,LogFileName}</c>, or <c>{file,LogFileName,LogFileOpts}</c>,
+	where <c>standard_io</c> is the default value for type. It's recommended
+	to not specify <c>LogFileOpts</c> if not absolutely necessary. The
+	default options used by the handler to open a file for logging are:
+	<c>raw</c>, <c>append</c> and <c>delayed_write</c>. The standard
+	handler does not have support for circular logging. Use the
+	<seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c>
+	</seealso> handler for this.</p></item>
+      <tag><c>filesync_repeat_interval</c></tag>
       <item>
-	<p>The level of log events that <c>logger</c> shall forward to
-	  this handler. Log events of the specified, or more severe
-	  levels, are forwarded.</p></item>
+	<p>This value (in milliseconds) specifies how often the handler will
+	do a file sync operation in order to make sure that buffered data gets
+	written to disk. The handler will repeatedly attempt this
+	operation, but only perform it if something has actually been logged
+	since the last sync. The default value is <c>5000</c> milliseconds.
+	If <c>no_repeat</c> is set as value, the repeated file sync operation
+	is disabled, and it will be the operating system settings that determine
+	how quickly or slowly data gets written	to disk. The user can also call
+	the <seealso marker="logger_std_h#filesync-1"><c>filesync/1</c></seealso>
+        function to perform a file sync.</p></item>
     </taglist>
-
+    <p>There are a number of other configuration parameters available, that are
+    to be used for customizing the overload protection behaviour. The same
+    parameters are used both in the standard handler and the disk_log handler,
+    and are documented in the
+    <seealso marker="logger_chapter#overload_protection"><c>User's Guide</c>
+    </seealso>.</p>
+    <p>Note that when changing the configuration of the handler in runtime, by
+    calling
+    <seealso marker="logger#set_handler_config-2"><c>logger:set_handler_config/2</c>
+    </seealso>, or
+    <seealso marker="logger#set_handler_config-3"><c>logger:set_handler_config/3</c>
+    </seealso>,
+    the <c>type</c> parameter may not be modified.</p>
+    <p>Example of adding a standard handler:</p>
+    <code type="none">
+logger:add_handler(my_standard_h, logger_std_h,
+                   #{level => info,
+                     filter_default => log,
+                     logger_std_h =>
+                              #{type => {file,"./system_info.log"},
+                                filesync_repeat_interval => 1000}}).
+    </code>
+    <p>In order to configure the default handler (that starts initially with
+    the kernel application) to log to file instead of <c>standard_io</c>,
+    use the kernel configuration parameter
+    <seealso marker="kernel_app#configuration"><c>logger_dest</c></seealso> with
+    value <c>{file,FileName}</c>. Example:</p>
+    <code type="none">
+erl -kernel logger_dest '{file,"./erl.log"}'
+    </code>
+    <p>An example of how to replace the standard handler with a disk_log handler
+    at startup can be found in the manual of
+    <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>.</p>
   </description>
 
-<!--  <funcs>
-  </funcs> -->
+  <funcs>
+
+    <func>
+      <name name="filesync" arity="1" clause_i="1"/>
+      <fsummary>Writes buffered data to disk.</fsummary>
+      <desc>
+        <p>Write buffered data to disk.</p>
+      </desc>
+    </func>
+
+  </funcs>
 
 </erlref>