path: root/lib/sasl/doc/src/error_logging.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1997</year><year>2013</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>log_mf_h</c> defined in
      <c>stdlib</c>.</p>
    <p>The <c>log_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>