<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- SASL Error Logging</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/sasl-2.2.1.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>System Application Support Libraries (SASL)</strong><br><strong>User's Guide</strong><br><small>Version 2.2.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="sasl_intro.html">
Top of chapter
</a></li>
<li title="About This Document"><a href="sasl_intro.html#id57316">About This Document</a></li>
</ul>
</li>
<li id="loadscrollpos" title="SASL Error Logging" expanded="true">SASL Error Logging<ul>
<li><a href="error_logging.html">
Top of chapter
</a></li>
<li title="Supervisor Report"><a href="error_logging.html#id58303">Supervisor Report</a></li>
<li title="Progress Report"><a href="error_logging.html#id61292">Progress Report</a></li>
<li title="Crash Report"><a href="error_logging.html#id57202">Crash Report</a></li>
<li title="Multi-File Error Report Logging"><a href="error_logging.html#id61415">Multi-File Error Report Logging</a></li>
<li title="Report Browser"><a href="error_logging.html#id57416">Report Browser</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>2 SASL Error Logging</h1>
<p>The SASL application introduces three types of reports:</p>
<ul>
<li>supervisor report</li>
<li>progress report</li>
<li>crash report.</li>
</ul>
<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
<span class="code">.app</span> file of SASL. See
<span class="bold_code"><a href="sasl_app.html">sasl(Application)</a></span>, and app(File)
in the Kernel Reference Manual
for the details.</p>
<h3><a name="id58303">2.1
Supervisor Report</a></h3>
<p>A supervisor report is issued when a supervised child terminates in
an unexpected way. A supervisor report contains the following
items:</p>
<dl>
<dt><strong>Supervisor.</strong></dt>
<dd>The name of the reporting supervisor.</dd>
<dt><strong>Context.</strong></dt>
<dd>Indicates in which phase the child terminated
from the supervisor's point of view. This can be
<span class="code">start_error</span>, <span class="code">child_terminated</span>, or
<span class="code">shutdown_error</span>.</dd>
<dt><strong>Reason.</strong></dt>
<dd>The termination reason.</dd>
<dt><strong>Offender.</strong></dt>
<dd>The start specification for the child.</dd>
</dl>
<h3><a name="id61292">2.2
Progress Report</a></h3>
<p>A progress report is issued whenever a supervisor starts or
restarts. A progress report contains the following items:</p>
<dl>
<dt><strong>Supervisor.</strong></dt>
<dd>The name of the reporting supervisor.</dd>
<dt><strong>Started.</strong></dt>
<dd>The start specification for the successfully
started child.</dd>
</dl>
<a name="CRASH"></a>
<h3><a name="id57202">2.3
Crash Report</a></h3>
<p>Processes started with the <span class="code">proc_lib:spawn</span> or
<span class="code">proc_lib:spawn_link</span> functions are wrapped within a
<span class="code">catch</span>. A crash report is issued whenever such a process
terminates with an unexpected reason, which is any reason other
than <span class="code">normal</span> or <span class="code">shutdown</span>. Processes using the
<span class="code">gen_server</span> and <span class="code">gen_fsm</span> behaviours are examples of
such processes. A crash report contains the following items:</p>
<dl>
<dt><strong>Crasher.</strong></dt>
<dd>Information about the crashing process is reported, such
as initial function call, exit reason, and message queue.</dd>
<dt><strong>Neighbours.</strong></dt>
<dd>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.</dd>
</dl>
<h4>An Example</h4>
<p>The following example shows the reports which are generated
when a process crashes. The example process is an
<span class="code">permanent</span> process supervised by the <span class="code">test_sup</span>
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
<span class="code">proc_lib:spawn/3</span> 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>
<div class="example"><pre>
=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}]
</pre></div>
<h3><a name="id61415">2.4
Multi-File Error Report Logging</a></h3>
<p>Multi-file error report logging is used to store error messages,
which are received by the <span class="code">error_logger</span>. 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
<span class="code">sasl</span> application in the Reference Manual for more details.</p>
<h3><a name="id57416">2.5
Report Browser</a></h3>
<p>The report browser is used to browse and format error reports
written by the error logger handler <span class="code">error_logger_mf_h</span>.</p>
<p>The <span class="code">error_logger_mf_h</span> 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
<span class="code">error_logger_mf_dir</span>.</p>
<h4>Starting the Report Browser</h4>
<p>Start the <span class="code">rb_server</span> with the function
<span class="code">rb:start([Options])</span> as shown in the following
example:</p>
<div class="example"><pre>
5><span class="bold_code">rb:start([{max, 20}]).</span>
rb: reading report...done.
rb: reading report...done.
rb: reading report...done.
rb: reading report...done.
</pre></div>
<h4>On-line Help</h4>
<p>Enter the command <strong>rb:help().</strong> to access the report
browser on-line help system.</p>
<h4>List Reports in the Server</h4>
<p>The function <span class="code">rb:list()</span> lists all loaded reports:</p>
<div class="example"><pre>
4><span class="bold_code">rb:list().</span>
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
</pre></div>
<h4>Show Reports</h4>
<p>To show details of a specific report, use the function
<span class="code">rb:show(Number)</span>:</p>
<div class="example"><pre>
10> <span class="bold_code">rb:show(1).</span>
7> <span class="bold_code">rb:show(4).</span>
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
</pre></div>
<h4>Search the Reports</h4>
<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 <span class="code">release_handler:mbj_func.</span> We could
then show reports as follows:</p>
<div class="example"><pre>
12><span class="bold_code">rb:grep("mbj_func").</span>
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_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 <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
</pre></div>
<h4>Stop the Server</h4>
<p>Stop the <span class="code">rb_server</span> with the function
<span class="code">rb:stop()</span>:</p>
<div class="example"><pre>
13><span class="bold_code">rb:stop().</span>
ok
</pre></div>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1252
