diff options
Diffstat (limited to 'lib/sasl/doc/src')
| -rw-r--r-- | lib/sasl/doc/src/appup.xml | 14 | ||||
| -rw-r--r-- | lib/sasl/doc/src/error_logging.xml | 53 | ||||
| -rw-r--r-- | lib/sasl/doc/src/notes.xml | 20 | ||||
| -rw-r--r-- | lib/sasl/doc/src/sasl_app.xml | 182 |
4 files changed, 181 insertions, 88 deletions
diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml index a43a966dcb..d9d339884f 100644 --- a/lib/sasl/doc/src/appup.xml +++ b/lib/sasl/doc/src/appup.xml @@ -249,9 +249,17 @@ <pre> {restart_application, Application} Application = atom()</pre> - <p>Restarting an application means that the application is - stopped and then started again, similar to using the instructions - <c>remove_application</c> and <c>add_application</c> in sequence.</p> + <p>Restarting an application means that the application is stopped + and then started again, similar to using the instructions + <c>remove_application</c> and <c>add_application</c> in sequence. + Note that, even if the application has been started before the + release upgrade is performed, <c>restart_application</c> may only + <c>load</c> it rather than <c>start</c> it, depending on the + application's <c>start type</c>: + If <c>Type = load</c>, the application is only loaded. + If <c>Type = none</c>, the application is not loaded and not + started, although the code for its modules is loaded. + </p> </section> <section> diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml index 4b2c960bbb..356b1f98e9 100644 --- a/lib/sasl/doc/src/error_logging.xml +++ b/lib/sasl/doc/src/error_logging.xml @@ -32,22 +32,52 @@ <rev>B</rev> <file>error_logging.xml</file> </header> + <note> + <p>The SASL error logging concept described in this section is + deprecated since Erlang/OTP 21.0, 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 primary log level to <c>info</c>, for example by + using the Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_level"> + <c>logger_level</c></seealso>.</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 +98,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 +113,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 +137,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 +196,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 +205,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/notes.xml b/lib/sasl/doc/src/notes.xml index e532c3cd6f..791e9c063a 100644 --- a/lib/sasl/doc/src/notes.xml +++ b/lib/sasl/doc/src/notes.xml @@ -31,6 +31,26 @@ </header> <p>This document describes the changes made to the SASL application.</p> +<section><title>SASL 3.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When upgrading with instruction 'restart_new_emulator', + the generated temporary boot file used 'kernelProcess' + statements from the old release instead of the new + release. This is now corrected.</p> + <p> + This correction is needed for upgrade to OTP-21.</p> + <p> + Own Id: OTP-15017</p> + </item> + </list> + </section> + +</section> + <section><title>SASL 3.1.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml index e0693fcb60..6f3b4fd7b0 100644 --- a/lib/sasl/doc/src/sasl_app.xml +++ b/lib/sasl/doc/src/sasl_app.xml @@ -34,12 +34,9 @@ <p>The SASL application provides the following services:</p> <list type="bulleted"> <item><c>alarm_handler</c></item> - <item><c>rb</c></item> <item><c>release_handler</c></item> <item><c>systools</c></item> </list> - <p>The SASL application also includes <c>error_logger</c> event - handlers for formatting SASL error and crash reports.</p> <note> <p>The SASL application in OTP has nothing to do with "Simple Authentication and Security Layer" (RFC 4422).</p> @@ -47,51 +44,101 @@ </description> <section> - <title>Error Logger Event Handlers</title> - <p>The following error logger event handlers are used by - the SASL application.</p> + <title>Configuration</title> + <p>The following configuration parameters are defined for the SASL + application. For more information about configuration parameters, see + <seealso marker="kernel:app"><c>app(4)</c></seealso> in Kernel.</p> + <p>All configuration parameters are optional.</p> + <taglist> + <tag><c><![CDATA[start_prg = string() ]]></c></tag> + <item> + <p>Specifies the program to be used when restarting the system + during release installation. Default is + <c>$OTP_ROOT/bin/start</c>.</p> + </item> + <tag><c><![CDATA[masters = [atom()] ]]></c></tag> + <item> + <p>Specifies the nodes used by this node to read/write release + information. This parameter is ignored if parameter + <c>client_directory</c> is not set.</p> + </item> + <tag><c><![CDATA[client_directory = string() ]]></c></tag> + <item> + <p>This parameter specifies the client directory at the master + nodes. For details, see + <seealso marker="doc/design_principles:release_handling">Release Handling</seealso> + in <em>OTP Design Principles</em>. This parameter is + ignored if parameter <c>masters</c> is not set.</p> + </item> + <tag><c><![CDATA[static_emulator = true | false ]]></c></tag> + <item> + <p>Indicates if the Erlang emulator is statically installed. A + node with a static emulator cannot switch dynamically to a + new emulator, as the executable files are written into memory + statically. This parameter is ignored if parameters <c>masters</c> + and <c>client_directory</c> are not set.</p> + </item> + <tag><c><![CDATA[releases_dir = string() ]]></c></tag> + <item> + <p>Indicates where the <c>releases</c> directory is located. + The release handler writes all its files to this directory. + If this parameter is not set, the OS environment parameter + <c>RELDIR</c> is used. By default, this is + <c>$OTP_ROOT/releases</c>.</p> + </item> + </taglist> + </section> + + <section> + <marker id="deprecated_error_logger_config"/> + <title>Deprecated Error Logger Event Handlers and Configuration</title> + <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, 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 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 default + logger handler started by the Kernel application. Progress + reports are by default stopped by the primary log level, but can + be enabled by setting this level to <c>info</c>, for example by + using the Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_level"> + <c>logger_level</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> <taglist> <tag><c>sasl_report_tty_h</c></tag> <item> <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#error_logger_format_depth">error_logger_format_depth</seealso> - in the Kernel application to limit how much detail is - printed in crash and supervisor reports.</p> + <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.</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#error_logger_format_depth">error_logger_format_depth</seealso> - in the Kernel application to limit the details - printed in crash and supervisor reports.</p> - </item> - <tag><c>log_mf_h</c></tag> - <item> - <p>This error logger writes <em>all</em> events sent to the - error logger to disk. Multiple files and log rotation are - used. For efficiency reasons, each event is written as a - binary. For more information about this handler, - see <seealso marker="stdlib:log_mf_h">the STDLIB Reference - Manual</seealso>.</p> - <p>To activate this event handler, three SASL - configuration parameters must be set, - <c>error_logger_mf_dir</c>, <c>error_logger_mf_maxbytes</c>, - and <c>error_logger_mf_maxfiles</c>. The next section provides - more information about the configuration parameters.</p> + <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.</p> </item> </taglist> - </section> - - <section> - <title>Configuration</title> - <p>The following configuration parameters are defined for the SASL - application. For more information about configuration parameters, see - <seealso marker="kernel:app"><c>app(4)</c></seealso> in Kernel.</p> - <p>All configuration parameters are optional.</p> + <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</c></seealso> to <c>true</c>. This + adds a second instance of the standard Logger handler, + named <c>sasl</c>, which only prints the SASL reports. No SASL + reports are then printed by the Kernel logger handler.</p> + <p>The <c>sasl</c> handler is configured according to the values + of the following SASL application environment variables.</p> <taglist> <tag><c><![CDATA[sasl_error_logger = Value ]]></c></tag> <item> @@ -124,6 +171,25 @@ <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 + be used. This event handler writes <em>all</em> events sent to + the error logger to disk. Multiple files and log rotation are + used. For efficiency reasons, each event is written as a + binary. For more information about this handler, + see <seealso marker="stdlib:log_mf_h">the STDLIB Reference + Manual</seealso>.</p> + <p>To activate this event handler, three SASL configuration + parameters must be + set:</p> + <taglist> <tag><c><![CDATA[error_logger_mf_dir = string() | false ]]></c></tag> <item> <p>Specifies in which directory <c>log_mf_h</c> is to store @@ -142,55 +208,19 @@ this parameter is undefined, the <c>log_mf_h</c> handler is not installed.</p> </item> - <tag><c><![CDATA[start_prg = string() ]]></c></tag> - <item> - <p>Specifies the program to be used when restarting the system - during release installation. Default is - <c>$OTP_ROOT/bin/start</c>.</p> - </item> - <tag><c><![CDATA[masters = [atom()] ]]></c></tag> - <item> - <p>Specifies the nodes used by this node to read/write release - information. This parameter is ignored if parameter - <c>client_directory</c> is not set.</p> - </item> - <tag><c><![CDATA[client_directory = string() ]]></c></tag> - <item> - <p>This parameter specifies the client directory at the master - nodes. For details, see - <seealso marker="doc/design_principles:release_handling">Release Handling</seealso> - in <em>OTP Design Principles</em>. This parameter is - ignored if parameter <c>masters</c> is not set.</p> - </item> - <tag><c><![CDATA[static_emulator = true | false ]]></c></tag> - <item> - <p>Indicates if the Erlang emulator is statically installed. A - node with a static emulator cannot switch dynamically to a - new emulator, as the executable files are written into memory - statically. This parameter is ignored if parameters <c>masters</c> - and <c>client_directory</c> are not set.</p> - </item> - <tag><c><![CDATA[releases_dir = string() ]]></c></tag> - <item> - <p>Indicates where the <c>releases</c> directory is located. - The release handler writes all its files to this directory. - If this parameter is not set, the OS environment parameter - <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> + <p>The new <seealso marker="kernel:logger_disk_log_h"> + <c>logger_disk_log_h</c></seealso> might be an alternative + to <c>log_mf_h</c> if log rotation is desired. This does, + however, write the log events in clear text and not as binaries.</p> + </section> <section> <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>, |