[Erlang Systems]

2 SASL Error Logging

The SASL application introduces three types of reports:

The SASL application adds a handler for these reports when it is started. According to the SASL configuration these error reports are written on screen, or to a specified file.

2.1 Supervisor Report

A supervisor report is issued when a supervised child terminates in an unexpected way. A supervisor report contains the following items:

Supervisor.
This is the name of the reporting supervisor.
Context.
This section indicates in which phase the child terminated from the supervisor's point of view. This can be start_error, child_terminated, or shutdown_error.
Reason.
This is the termination reason.
Offender.
This is the start specification for the child.

2.2 Progress Report

A progress report is issued whenever a supervisor starts or restarts. A progress report contains the following items:

Supervisor.
This is the name of the reporting supervisor.
Started.
This is the start specification for the successfully started child.

2.3 Crash Report

Processes started with the proc_lib:spawn or proc_lib:spawn_link functions are wrapped within a catch. A crash report is issued whenever such a process terminates with an unexpected reason, which is any reason other than normal or shutdown. Processes using the gen_server and gen_fsm behaviours are examples of such processes. A crash report contains the following items:

Crasher.
Information about the crashing process is reported, such as initial function call, exit reason, and message queue.
Neighbours.
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.

2.3.1 An Example

The following example shows the reports which are generated when a process crashes. The example process is an permanent process supervised by the test_sup 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 proc_lib:spawn/3 function. The supervisor generates a supervisor report which shows what process crashed, and a progress report is generated when the process is finally re-started.

=ERROR REPORT==== 27-May-1996::13:38:56 ===
<0.63.0>: Divide by zero !
 
=CRASH REPORT==== 27-May-1996::13:38:56 ===
  crasher:
    pid: <0.63.0>
    registered_name: []
    error_info: {badarith,{test,s,[]}}
    initial_call: {test,s,[]}
    ancestors: [test_sup,<0.46.0>]
    messages: []
    links: [<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,<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,<0.64.0>},
                  {name,test},
                  {mfa,{test,t,[]}},
                  {restart_type,permanent},
                  {shutdown,200},
                  {child_type,worker}]
 

2.4 Multi-File Error Report Logging

Multi-file error report logging is used to store error messages which are received by the error_logger. 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.

Refer to SASL Applications in the Reference Manual for more details.

2.5 Report Browser

The report browser is used to browse and format error reports written by the error logger handler error_logger_mf_h.

The error_logger_mf_h handler writes all reports to a report logging directory. This directory is specified when configuring the SASL application.

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 direcory is specified, the browser reads reports from the SASL error_logger_mf_dir.

2.5.1 Starting the Report Browser

Start the rb_server with the function rb:start([Options]) as shown in the following example:

5> rb:start([{max, 20}]).
rb: reading report...done.
rb: reading report...done.
rb: reading report...done.
rb: reading report...done.

2.5.2 On-line Help

Enter the command rb:help(). ro access the report browser on-line help system.

2.5.3 List Reports in the Server

The function rb:list() lists all loaded reports:

4> rb:list().
  No                Type          Process       Date     Time
  ==                ====          =======       ====     ====
  20            progress         <0.17.0> 1996-10-16 16:14:54
  19            progress         <0.14.0> 1996-10-16 16:14:55
  18               error         <0.15.0> 1996-10-16 16:15:02
  17            progress         <0.14.0> 1996-10-16 16:15:06
  16            progress         <0.38.0> 1996-10-16 16:15:12
  15            progress         <0.17.0> 1996-10-16 16:16:14
  14            progress         <0.17.0> 1996-10-16 16:16:14
  13            progress         <0.17.0> 1996-10-16 16:16:14
  12            progress         <0.14.0> 1996-10-16 16:16:14
  11               error         <0.17.0> 1996-10-16 16:16:21
  10               error         <0.17.0> 1996-10-16 16:16:21
   9        crash_report  release_handler 1996-10-16 16:16:21
   8   supervisor_report         <0.17.0> 1996-10-16 16:16:21
   7            progress         <0.17.0> 1996-10-16 16:16:21
   6            progress         <0.17.0> 1996-10-16 16:16:36
   5            progress         <0.17.0> 1996-10-16 16:16:36
   4            progress         <0.17.0> 1996-10-16 16:16:36
   3            progress         <0.14.0> 1996-10-16 16:16:36
   2               error         <0.15.0> 1996-10-16 16:17:04
   1            progress         <0.14.0> 1996-10-16 16:17:09
ok
        

2.5.4 Show Reports

To show details of a specific report, use the function rb:show(Number):

10> rb:show(1).
7> rb:show(4).
 
PROGRESS REPORT  <0.20.0>                                   1996-10-16 16:16:36
===============================================================================
supervisor                                                     {local,sasl_sup}
started
         [{pid,<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  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================
Crashing process                                                               
   pid                                                                 <0.24.0>
   registered_name                                              release_handler
   error_info                             {undef,{release_handler,mbj_func,[]}}
   initial_call
         {gen,init_it,
             [gen_server,
              <0.20.0>,
              <0.20.0>,
              {erlang,register},
              release_handler,
              release_handler,
              [],
              []]}
   ancestors                                                [sasl_sup,<0.18.0>]
   messages                                                                  []
   links                                                    [<0.23.0>,<0.20.0>]
   dictionary                                                                []
   trap_exit                                                              false
   status                                                               running
   heap_size                                                                610
   stack_size                                                               142
   reductions                                                                54
 
ok
        

2.5.5 Search the Reports

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 release_handler:mbj_func. We could then show reports as follows:

12> rb:grep("mbj_func").          
Found match in report number 11
 
ERROR REPORT  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================
 
** undefined function: release_handler:mbj_func[] **
Found match in report number 10
 
ERROR REPORT  <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_jam_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  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================
Crashing process                                                               
   pid                                                                 <0.24.0>
   registered_name                                              release_handler
   error_info                             {undef,{release_handler,mbj_func,[]}}
   initial_call
         {gen,init_it,
             [gen_server,
              <0.20.0>,
              <0.20.0>,
              {erlang,register},
              release_handler,
              release_handler,
              [],
              []]}
   ancestors                                                [sasl_sup,<0.18.0>]
   messages                                                                  []
   links                                                    [<0.23.0>,<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  <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                                                                 <0.24.0>
   name                                                         release_handler
   start_function                               {release_handler,start_link,[]}
   restart_type                                                       permanent
   shutdown                                                                2000
   child_type                                                            worker
 
ok
        
2.5.5.1 Stop the Server

Stop the rb_server as follows with the function rb:stop():

13> rb:stop().
ok

Copyright © 1991-98 Ericsson Telecom AB