The R13B03 release.OTP_R13B03

1 files changed, 385 insertions, 0 deletions

diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml
new file mode 100644
index 0000000000..5707bc4d69
--- /dev/null
+++ b/lib/sasl/doc/src/error_logging.xml
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>SASL Error Logging</title>
+    <prepared>Magnus Fr&ouml;berg</prepared>
+    <responsible>Bjarne D&auml;cker</responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>1999-04-13</date>
+    <rev>B</rev>
+    <file>error_logging.xml</file>
+  </header>
+  <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, i.e the environment variables
+    in the SASL application specification, which is found in the 
+    <c>.app</c> file of SASL. See 
+    <seealso marker="sasl_app">sasl(Application)</seealso>, and  app(File) 
+    in the Kernel Reference Manual
+    for the details.</p>
+
+  <section>
+    <title>Supervisor Report</title>
+    <p>A supervisor report is issued when a supervised child terminates in
+      an unexpected way. A supervisor report contains the following
+      items:</p>
+    <taglist>
+      <tag>Supervisor.</tag>
+      <item>The name of the reporting supervisor.</item>
+      <tag>Context.</tag>
+      <item>Indicates in which phase the child terminated
+       from the supervisor's point of view. This can be
+      <c>start_error</c>, <c>child_terminated</c>, or
+      <c>shutdown_error</c>.</item>
+      <tag>Reason.</tag>
+      <item>The termination reason.</item>
+      <tag>Offender.</tag>
+      <item>The start specification for the child.</item>
+    </taglist>
+  </section>
+
+  <section>
+    <title>Progress Report</title>
+    <p>A progress report is issued whenever a supervisor starts or
+      restarts. A progress report contains the following items:</p>
+    <taglist>
+      <tag>Supervisor.</tag>
+      <item>The name of the reporting supervisor.</item>
+      <tag>Started.</tag>
+      <item>The start specification for the successfully
+       started child.</item>
+    </taglist>
+    <marker id="CRASH"></marker>
+  </section>
+
+  <section>
+    <title>Crash Report</title>
+    <p>Processes started with the <c>proc_lib:spawn</c> or
+      <c>proc_lib:spawn_link</c> functions are wrapped within a
+      <c>catch</c>. A crash report is issued whenever such a process
+      terminates with an unexpected reason, which is any reason other
+      than <c>normal</c> or <c>shutdown</c>. Processes using the
+      <c>gen_server</c> and <c>gen_fsm</c> behaviours are examples of
+      such processes. A crash report contains the following items:</p>
+    <taglist>
+      <tag>Crasher.</tag>
+      <item>Information about the crashing process is reported, such
+       as initial function call, exit reason, and message queue.</item>
+      <tag>Neighbours.</tag>
+      <item>Information about processes which are linked to the crashing
+       process and do not trap exits. These processes are the
+       neighbours which will terminate because of this process
+       crash. The information gathered is the same as the information
+       for Crasher, shown in the previous item.</item>
+    </taglist>
+
+    <section>
+      <title>An Example</title>
+      <p>The following example shows the reports which are generated
+        when a process crashes. The example process is an
+        <c>permanent</c> process supervised by the <c>test_sup</c>
+        supervisor. A division by zero is executed and the error is
+        first reported by the faulty process. A crash report is
+        generated as the process was started using the
+        <c>proc_lib:spawn/3</c> function. The supervisor generates a
+        supervisor report showing the process that has crashed, and then a
+        progress report is generated when the process is finally
+        re-started.</p>
+      <pre>
+        =ERROR REPORT==== 27-May-1996::13:38:56 ===
+        &lt;0.63.0>: Divide by zero !
+        
+        =CRASH REPORT==== 27-May-1996::13:38:56 ===
+        crasher:
+        pid: &lt;0.63.0>
+        registered_name: []
+        error_info: {badarith,{test,s,[]}}
+        initial_call: {test,s,[]}
+        ancestors: [test_sup,&lt;0.46.0>]
+        messages: []
+        links: [&lt;0.47.0>]
+        dictionary: []
+        trap_exit: false
+        status: running
+        heap_size: 128
+        stack_size: 128
+        reductions: 348
+        neighbours:
+        
+        =SUPERVISOR REPORT==== 27-May-1996::13:38:56 ===
+        Supervisor: {local,test_sup}
+        Context:    child_terminated
+        Reason:     {badarith,{test,s,[]}}
+        Offender:   [{pid,&lt;0.63.0>},
+        {name,test},
+        {mfa,{test,t,[]}},
+        {restart_type,permanent},
+        {shutdown,200},
+        {child_type,worker}]
+        
+        
+        =PROGRESS REPORT==== 27-May-1996::13:38:56 ===
+        Supervisor: {local,test_sup}
+        Started:  [{pid,&lt;0.64.0>},
+        {name,test},
+        {mfa,{test,t,[]}},
+        {restart_type,permanent},
+        {shutdown,200},
+        {child_type,worker}]
+      </pre>
+    </section>
+  </section>
+
+  <section>
+    <title>Multi-File Error Report Logging</title>
+    <p>Multi-file error report logging is used to store error messages,
+      which are received by the <c>error_logger</c>. The error messages
+      are stored in several files and each file is smaller than a
+      specified amount of kilobytes, and no more than a specified number
+      of files exist at the same time. The logging is very fast because
+      each error message is written as a binary term.</p>
+    <p>Refer to
+      <c>sasl</c> application in the Reference Manual for more details.</p>
+  </section>
+
+  <section>
+    <title>Report Browser</title>
+    <p>The report browser is used to browse and format error reports
+      written by the error logger handler <c>error_logger_mf_h</c>.</p>
+    <p>The <c>error_logger_mf_h</c> handler writes all reports to a
+      report logging directory. This directory is specified when
+      configuring the SASL application.</p>
+    <p>If the report browser is
+      used off-line, the reports can be copied to another directory
+      which is specified when starting the browser. If no such directory
+      is specified, the browser reads reports from the SASL
+      <c>error_logger_mf_dir</c>.</p>
+
+    <section>
+      <title>Starting the Report Browser</title>
+      <p>Start the <c>rb_server</c> with the function
+        <c>rb:start([Options])</c> as shown in the following
+        example:</p>
+      <pre>
+
+        5><input>rb:start([{max, 20}]).</input>
+        rb: reading report...done.
+        rb: reading report...done.
+        rb: reading report...done.
+        rb: reading report...done.
+      </pre>
+    </section>
+
+    <section>
+      <title>On-line Help</title>
+      <p>Enter the command <em>rb:help().</em> to access the report
+        browser on-line help system.</p>
+    </section>
+
+    <section>
+      <title>List Reports in the Server</title>
+      <p>The function <c>rb:list()</c> lists all loaded reports:</p>
+      <pre>
+
+        4><input>rb:list().</input>
+        No                Type          Process       Date     Time
+        ==                ====          =======       ====     ====
+        20            progress         &lt;0.17.0> 1996-10-16 16:14:54
+        19            progress         &lt;0.14.0> 1996-10-16 16:14:55
+        18               error         &lt;0.15.0> 1996-10-16 16:15:02
+        17            progress         &lt;0.14.0> 1996-10-16 16:15:06
+        16            progress         &lt;0.38.0> 1996-10-16 16:15:12
+        15            progress         &lt;0.17.0> 1996-10-16 16:16:14
+        14            progress         &lt;0.17.0> 1996-10-16 16:16:14
+        13            progress         &lt;0.17.0> 1996-10-16 16:16:14
+        12            progress         &lt;0.14.0> 1996-10-16 16:16:14
+        11               error         &lt;0.17.0> 1996-10-16 16:16:21
+        10               error         &lt;0.17.0> 1996-10-16 16:16:21
+        9        crash_report  release_handler 1996-10-16 16:16:21
+        8   supervisor_report         &lt;0.17.0> 1996-10-16 16:16:21
+        7            progress         &lt;0.17.0> 1996-10-16 16:16:21
+        6            progress         &lt;0.17.0> 1996-10-16 16:16:36
+        5            progress         &lt;0.17.0> 1996-10-16 16:16:36
+        4            progress         &lt;0.17.0> 1996-10-16 16:16:36
+        3            progress         &lt;0.14.0> 1996-10-16 16:16:36
+        2               error         &lt;0.15.0> 1996-10-16 16:17:04
+        1            progress         &lt;0.14.0> 1996-10-16 16:17:09
+        ok
+      </pre>
+    </section>
+
+    <section>
+      <title>Show Reports</title>
+      <p>To show details of a specific report, use the function
+        <c>rb:show(Number)</c>:</p>
+      <pre>
+
+10> <input>rb:show(1).</input>
+7> <input>rb:show(4).</input>
+        
+PROGRESS REPORT  &lt;0.20.0>                                   1996-10-16 16:16:36
+===============================================================================
+supervisor                                                     {local,sasl_sup}
+started
+[{pid,&lt;0.24.0>},
+{name,release_handler},
+{mfa,{release_handler,start_link,[]}},
+{restart_type,permanent},
+{shutdown,2000},
+{child_type,worker}]
+        
+ok
+8> rb:show(9).
+        
+CRASH REPORT  &lt;0.24.0>                                      1996-10-16 16:16:21
+===============================================================================
+Crashing process                                                               
+pid                                                                 &lt;0.24.0>
+registered_name                                              release_handler
+error_info                             {undef,{release_handler,mbj_func,[]}}
+initial_call
+{gen,init_it,
+[gen_server,
+&lt;0.20.0>,
+&lt;0.20.0>,
+{erlang,register},
+release_handler,
+release_handler,
+[],
+[]]}
+ancestors                                                [sasl_sup,&lt;0.18.0>]
+messages                                                                  []
+links                                                    [&lt;0.23.0>,&lt;0.20.0>]
+dictionary                                                                []
+trap_exit                                                              false
+status                                                               running
+heap_size                                                                610
+stack_size                                                               142
+reductions                                                                54
+
+ok
+      </pre>
+    </section>
+
+    <section>
+      <title>Search the Reports</title>
+      <p>It is possible to show all reports which contain a common
+        pattern. Suppose a process crashes because it tries to call a
+        non-existing function <c>release_handler:mbj_func.</c> We could
+        then show reports as follows:</p>
+      <pre>
+
+12><input>rb:grep("mbj_func").</input>          
+Found match in report number 11
+        
+ERROR REPORT  &lt;0.24.0>                                      1996-10-16 16:16:21
+===============================================================================
+        
+** undefined function: release_handler:mbj_func[] **
+Found match in report number 10
+
+ERROR REPORT  &lt;0.24.0>                                      1996-10-16 16:16:21
+===============================================================================
+        
+** Generic server release_handler terminating 
+** Last message in was {unpack_release,hej}
+** When Server state == {state,[],
+"/home/dup/otp2/otp_beam_sunos5_p1g_7",
+[{release,
+"OTP  APN 181 01",
+"P1G",
+undefined,
+[],
+permanent}],
+undefined}
+** Reason for termination == 
+** {undef,{release_handler,mbj_func,[]}}
+Found match in report number 9
+        
+CRASH REPORT  &lt;0.24.0>                                      1996-10-16 16:16:21
+===============================================================================
+Crashing process                                                               
+pid                                                                 &lt;0.24.0>
+registered_name                                              release_handler
+error_info                             {undef,{release_handler,mbj_func,[]}}
+initial_call
+{gen,init_it,
+[gen_server,
+&lt;0.20.0>,
+&lt;0.20.0>,
+{erlang,register},
+release_handler,
+release_handler,
+[],
+[]]}
+ancestors                                                [sasl_sup,&lt;0.18.0>]
+messages                                                                  []
+links                                                    [&lt;0.23.0>,&lt;0.20.0>]
+dictionary                                                                []
+trap_exit                                                              false
+status                                                               running
+heap_size                                                                610
+stack_size                                                               142
+reductions                                                                54
+        
+Found match in report number 8
+        
+SUPERVISOR REPORT  &lt;0.20.0>                                 1996-10-16 16:16:21
+===============================================================================
+Reporting supervisor                                           {local,sasl_sup}
+        
+Child process                                                                  
+errorContext                                                child_terminated
+reason                                 {undef,{release_handler,mbj_func,[]}}
+pid                                                                 &lt;0.24.0>
+name                                                         release_handler
+start_function                               {release_handler,start_link,[]}
+restart_type                                                       permanent
+shutdown                                                                2000
+child_type                                                            worker
+        
+ok
+      </pre>
+    </section>
+
+    <section>
+      <title>Stop the Server</title>
+      <p>Stop the <c>rb_server</c>  with the function
+        <c>rb:stop()</c>:</p>
+      <pre>
+
+13><input>rb:stop().</input>
+ok
+      </pre>
+    </section>
+  </section>
+</chapter>
+