diff options
Diffstat (limited to 'lib/sasl/doc/src')
| -rw-r--r-- | lib/sasl/doc/src/error_logging.xml | 52 | ||||
| -rw-r--r-- | lib/sasl/doc/src/sasl_app.xml | 43 |
2 files changed, 64 insertions, 31 deletions
diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml index 4b2c960bbb..8731b73599 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_progress_reports"> + <c>logger_progress_reports</c></seealso> to <c>log</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 48b0b8eafb..be275879ee 100644 --- a/lib/sasl/doc/src/sasl_app.xml +++ b/lib/sasl/doc/src/sasl_app.xml @@ -86,30 +86,26 @@ <c>RELDIR</c> is used. By default, this is <c>$OTP_ROOT/releases</c>.</p> </item> - <tag><c><![CDATA[utc_log = true | false ]]></c></tag> - <item> - <p>If set to <c>true</c>, all dates in textual log outputs are - displayed in Universal Coordinated Time with the string - <c>UTC</c> appended.</p> - </item> </taglist> </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 + <p>In Erlang/OTP 21.0, a new API for logging was added. The old <c>error_logger</c> event manager, and event handlers - running on this manager, will still work, but they are not used + running on this manager, 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 + reports are by default stopped by a filter, but can 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_progress_reports"> + <c>logger_progress_reports</c></seealso> to <c>log</c>.</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> @@ -119,32 +115,28 @@ <p>Formats and writes <em>supervisor reports</em>, <em>crash reports</em>, and <em>progress reports</em> to <c>stdio</c>. This error logger event handler uses - <seealso marker="kernel:kernel_app#logger_format_depth"><c>logger_format_depth</c></seealso> + <seealso marker="kernel:kernel_app#deprecated-configuration-parameters"><c>error_logger_format_depth</c></seealso> in the Kernel application to limit how much detail is printed - in crash and supervisor reports. If <c>logger_format_depth</c> - is not set, it uses the old <c>error_logger_format_depth</c> - instead.</p> + in crash and supervisor reports.</p> </item> <tag><c>sasl_report_file_h</c></tag> <item> <p>Formats and writes <em>supervisor reports</em>, <em>crash report</em>, and <em>progress report</em> to a single file. This error logger event handler uses - <seealso marker="kernel:kernel_app#logger_format_depth"><c>logger_format_depth</c></seealso> + <seealso marker="kernel:kernel_app#deprecated-configuration-parameters"><c>error_logger_format_depth</c></seealso> in the Kernel application to limit the details printed in - crash and supervisor reports. If <c>logger_format_depth</c> is - not set, it uses the old <c>error_logger_format_depth</c> - instead.</p> + crash and supervisor reports.</p> </item> </taglist> <p>A similar behaviour, but still using the new logger API, can be obtained by setting the Kernel application environment variable <seealso marker="kernel:kernel_app#logger_sasl_compatible"><c>logger_sasl_compatible=true</c></seealso>. This will add a second instance of the standard logger handler - named <c>sasl_h</c>, which will only print the SASL reports. No + named <c>sasl</c>, which will only print the SASL reports. No SASL reports will then be printed by the Kernel logger handler.</p> - <p>The <c>sasl_h</c> handler will be configured according to the + <p>The <c>sasl</c> handler will be configured according to the values of the following SASL application environment variables.</p> <taglist> @@ -179,6 +171,12 @@ <c>sasl_error_logger</c> to error reports or progress reports, or both. Default is <c>all</c>.</p> </item> + <tag><marker id="utc_log"/><c><![CDATA[utc_log = true | false ]]></c></tag> + <item> + <p>If set to <c>true</c>, all dates in textual log outputs are + displayed in Universal Coordinated Time with the string + <c>UTC</c> appended.</p> + </item> </taglist> <p>The error logger event handler <c>log_mf_h</c> can also still @@ -222,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>, |