From a9a6b803a60793d42a74e0f1693a7594dffb6bc3 Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Thu, 17 May 2018 18:19:57 +0200
Subject: Improve documentation of logger and error_logger

---
 lib/sasl/doc/src/error_logging.xml | 52 +++++++++++++++++++++++++++++++-------
 lib/sasl/doc/src/sasl_app.xml      |  9 ++++---
 2 files changed, 49 insertions(+), 12 deletions(-)

(limited to 'lib/sasl/doc')

diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml
index 4b2c960bbb..44506ffdad 100644
--- a/lib/sasl/doc/src/error_logging.xml
+++ b/lib/sasl/doc/src/error_logging.xml
@@ -32,22 +32,51 @@
     <rev>B</rev>
     <file>error_logging.xml</file>
     </header>
+  <note>
+    <p>The SASL error logging concept desribed in this section is
+      deprecated since OTP-21, when the
+      new <seealso marker="kernel:logger_chapter">logging
+      API</seealso> was introduced.</p>
+    <p>The new default behaviour is that the SASL application no
+      longer affects which log events that are logged.
+      <seealso marker="#supervisor_report">Supervisor
+      reports</seealso> and <seealso marker="#crash_report">crash
+      reports</seealso> are logged via the default logger handler
+      which is setup by
+      Kernel. <seealso marker="#progress_report">Progress
+      reports</seealso> are by default not logged, but can be enabled
+      by setting the Kernel configuration
+      parameter <seealso marker="kernel:kernel_app#logger_log_progress">
+	<c>logger_log_progress</c></seealso> to <c>true</c>.</p>
+    <p>The old SASL error logging behaviour can be re-enabled by setting the
+      Kernel configuration
+      parameter <seealso marker="kernel:kernel_app#logger_sasl_compatible">
+	<c>logger_sasl_compatible</c></seealso> to <c>true</c>.</p>
+    <p>The mechanism
+      for <seealso marker="#multi_file_logging">multi-file error report
+      logging</seealso> as described in this section is also kept for
+      backwards compatibility. However, the new logging API also
+      introduces <seealso marker="kernel:logger_disk_log_h">
+	<c>logger_disk_log_h(3)</c></seealso>, which is a logger
+      handler that can print to multiple files
+      using <seealso marker="kernel:disk_log"><c>disk_log(3)</c></seealso>.</p>
+  </note>
+
+  <section>
+    <title>SASL reports</title>
   <p>The SASL application introduces three types of reports:</p>
   <list type="bulleted">
     <item>Supervisor report</item>
     <item>Progress report</item>
     <item>Crash report</item>
   </list>
-  <p>When the SASL application is started, it adds a handler that
-    formats and writes these reports, as specified in the configuration
-    parameters for SASL, that is, the environment variables
-    in the SASL application specification, which is found in the
-    <c>.app</c> file of SASL. For details, see the
-    <seealso marker="sasl_app"><c>sasl(6)</c></seealso> application in the
-    Reference Manual and the <seealso marker="kernel:app"><c>app(4)</c></seealso>
-    file in the Kernel Reference Manual.</p>
+  <p>When the SASL application is started, it adds a logger handler
+    that formats and writes these reports, as specified in
+    the <seealso marker="sasl_app#deprecated_error_logger_config">configuration
+    parameters for SASL</seealso></p>
 
   <section>
+    <marker id="supervisor_report"/>
     <title>Supervisor Report</title>
     <p>A supervisor report is issued when a supervised child terminates
       unexpectedly. A supervisor report contains the following
@@ -68,6 +97,7 @@
   </section>
 
   <section>
+    <marker id="progress_report"/>
     <title>Progress Report</title>
     <p>A progress report is issued when a supervisor starts or
       restarts a child. A progress report contains the following items:</p>
@@ -82,6 +112,7 @@
   </section>
 
   <section>
+    <marker id="crash_report"/>
     <title>Crash Report</title>
     <p>Processes started with functions 
       <seealso marker="stdlib:proc_lib#spawn/1"><c>proc_lib:spawn</c></seealso> or
@@ -105,6 +136,7 @@
        crash. The information gathered is the same as the information
        for Crasher, described in the previous item.</p></item>
     </taglist>
+    </section>
 
     <section>
       <title>Example</title>
@@ -163,6 +195,7 @@
   </section>
 
   <section>
+    <marker id="multi_file_logging"/>
     <title>Multi-File Error Report Logging</title>
     <p>Multi-file error report logging is used to store error messages
       received by <c>error_logger</c>. The error messages
@@ -171,7 +204,8 @@
       of files exist at the same time. The logging is very fast, as
       each error message is written as a binary term.</p>
     <p>For more details, see the
-      <seealso marker="sasl_app"><c>sasl(6)</c></seealso>
+      <seealso marker="sasl_app#deprecated_error_logger_config">
+	<c>sasl(6)</c></seealso>
       application in the Reference Manual.</p>
   </section>
 
diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml
index 26b9bece2a..eb1e87d9a3 100644
--- a/lib/sasl/doc/src/sasl_app.xml
+++ b/lib/sasl/doc/src/sasl_app.xml
@@ -90,20 +90,22 @@
   </section>
 
   <section>
+    <marker id="deprecated_error_logger_config"/>
     <title>Deprecated Error Logger Event Handlers and Configuration</title>
     <p>In OTP-21, a new API for logging was added to Erlang/OTP. The
       old <c>error_logger</c> event manager, and event handlers
       running on this manager, will still work, but they are not used
       by default.</p>
     <p>The error logger event handlers <c>sasl_report_tty_h</c>
-      and <c>sasl_report_file_h</c>, were earliger used for printing
+      and <c>sasl_report_file_h</c>, were earlier used for printing
       the so called SASL reports, i.e. <em>supervisor
       reports</em>, <em>crash reports</em>, and <em>progress
-      reports</em>. These reports are now also printed by the standard
+      reports</em>. These reports are now also printed by the default
       logger handler started by the Kernel application. Progress
       reports are by default stopped by a filter, but can easily be
       added by setting the Kernel configuration
-      parameter <seealso marker="kernel:kernel_app#logger_log_progress"><c>logger_log_progress=true</c></seealso>.</p>
+      parameter <seealso marker="kernel:kernel_app#logger_log_progress">
+      <c>logger_log_progress=true</c></seealso>.</p>
     <p>If the old error logger event handlers are still desired, they
       must be added by
       calling <c>error_logger:add_report_handler/1,2</c>.</p>
@@ -218,6 +220,7 @@
     <title>See Also</title>
     <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>,
       <seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>,
+      <seealso marker="kernel:logger"><c>logger(3)</c></seealso>,
       <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>,
       <seealso marker="rb"><c>rb(3)</c></seealso>,
       <seealso marker="release_handler"><c>release_handler(3)</c></seealso>,
-- 
cgit v1.2.3