aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc/src/error_logging.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/sasl/doc/src/error_logging.xml')
-rw-r--r--lib/sasl/doc/src/error_logging.xml385
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>
+