1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>SASL Error Logging</title>
27
<prepared>Magnus Fröberg</prepared>
28
<responsible>Bjarne Däcker</responsible>
32
<date>1999-04-13</date>
34
<file>error_logging.sgml</file>
36
<p>The SASL application introduces three types of reports:</p>
37
<list type="bulleted">
38
<item>supervisor report</item>
39
<item>progress report</item>
40
<item>crash report.</item>
42
<p>When the SASL application is started, it adds a handler that
43
formats and writes these reports, as specified in the
44
configuration parameters for sasl, i.e the environment variables
45
in the SASL application specification, which is found in the
46
<c>.app</c> file of SASL. See
47
<seealso marker="sasl_app">sasl(Application)</seealso>, and app(File)
48
in the Kernel Reference Manual
52
<title>Supervisor Report</title>
53
<p>A supervisor report is issued when a supervised child terminates in
54
an unexpected way. A supervisor report contains the following
57
<tag>Supervisor.</tag>
58
<item>The name of the reporting supervisor.</item>
60
<item>Indicates in which phase the child terminated
61
from the supervisor's point of view. This can be
62
<c>start_error</c>, <c>child_terminated</c>, or
63
<c>shutdown_error</c>.</item>
65
<item>The termination reason.</item>
67
<item>The start specification for the child.</item>
72
<title>Progress Report</title>
73
<p>A progress report is issued whenever a supervisor starts or
74
restarts. A progress report contains the following items:</p>
76
<tag>Supervisor.</tag>
77
<item>The name of the reporting supervisor.</item>
79
<item>The start specification for the successfully
82
<marker id="CRASH"></marker>
86
<title>Crash Report</title>
87
<p>Processes started with the <c>proc_lib:spawn</c> or
88
<c>proc_lib:spawn_link</c> functions are wrapped within a
89
<c>catch</c>. A crash report is issued whenever such a process
90
terminates with an unexpected reason, which is any reason other
91
than <c>normal</c> or <c>shutdown</c>. Processes using the
92
<c>gen_server</c> and <c>gen_fsm</c> behaviours are examples of
93
such processes. A crash report contains the following items:</p>
96
<item>Information about the crashing process is reported, such
97
as initial function call, exit reason, and message queue.</item>
98
<tag>Neighbours.</tag>
99
<item>Information about processes which are linked to the crashing
100
process and do not trap exits. These processes are the
101
neighbours which will terminate because of this process
102
crash. The information gathered is the same as the information
103
for Crasher, shown in the previous item.</item>
107
<title>An Example</title>
108
<p>The following example shows the reports which are generated
109
when a process crashes. The example process is an
110
<c>permanent</c> process supervised by the <c>test_sup</c>
111
supervisor. A division by zero is executed and the error is
112
first reported by the faulty process. A crash report is
113
generated as the process was started using the
114
<c>proc_lib:spawn/3</c> function. The supervisor generates a
115
supervisor report showing the process that has crashed, and then a
116
progress report is generated when the process is finally
119
\011=ERROR REPORT==== 27-May-1996::13:38:56 ===
120
\011<0.63.0>: Divide by zero !
122
\011=CRASH REPORT==== 27-May-1996::13:38:56 ===
125
\011registered_name: []
126
\011error_info: {badarith,{test,s,[]}}
127
\011initial_call: {test,s,[]}
128
\011ancestors: [test_sup,<0.46.0>]
130
\011links: [<0.47.0>]
139
\011=SUPERVISOR REPORT==== 27-May-1996::13:38:56 ===
140
\011Supervisor: {local,test_sup}
141
\011Context: child_terminated
142
\011Reason: {badarith,{test,s,[]}}
143
\011Offender: [{pid,<0.63.0>},
145
\011{mfa,{test,t,[]}},
146
\011{restart_type,permanent},
148
\011{child_type,worker}]
151
\011=PROGRESS REPORT==== 27-May-1996::13:38:56 ===
152
\011Supervisor: {local,test_sup}
153
\011Started: [{pid,<0.64.0>},
155
\011{mfa,{test,t,[]}},
156
\011{restart_type,permanent},
158
\011{child_type,worker}]
164
<title>Multi-File Error Report Logging</title>
165
<p>Multi-file error report logging is used to store error messages,
166
which are received by the <c>error_logger</c>. The error messages
167
are stored in several files and each file is smaller than a
168
specified amount of kilobytes, and no more than a specified number
169
of files exist at the same time. The logging is very fast because
170
each error message is written as a binary term.</p>
172
<c>sasl</c> application in the Reference Manual for more details.</p>
176
<title>Report Browser</title>
177
<p>The report browser is used to browse and format error reports
178
written by the error logger handler <c>error_logger_mf_h</c>.</p>
179
<p>The <c>error_logger_mf_h</c> handler writes all reports to a
180
report logging directory. This directory is specified when
181
configuring the SASL application.</p>
182
<p>If the report browser is
183
used off-line, the reports can be copied to another directory
184
which is specified when starting the browser. If no such directory
185
is specified, the browser reads reports from the SASL
186
<c>error_logger_mf_dir</c>.</p>
189
<title>Starting the Report Browser</title>
190
<p>Start the <c>rb_server</c> with the function
191
<c>rb:start([Options])</c> as shown in the following
195
\0115><input>rb:start([{max, 20}]).</input>
196
\011rb: reading report...done.
197
\011rb: reading report...done.
198
\011rb: reading report...done.
199
\011rb: reading report...done.
204
<title>On-line Help</title>
205
<p>Enter the command <em>rb:help().</em> to access the report
206
browser on-line help system.</p>
210
<title>List Reports in the Server</title>
211
<p>The function <c>rb:list()</c> lists all loaded reports:</p>
214
\0114><input>rb:list().</input>
215
\011No Type Process Date Time
216
\011== ==== ======= ==== ====
217
\01120 progress <0.17.0> 1996-10-16 16:14:54
218
\01119 progress <0.14.0> 1996-10-16 16:14:55
219
\01118 error <0.15.0> 1996-10-16 16:15:02
220
\01117 progress <0.14.0> 1996-10-16 16:15:06
221
\01116 progress <0.38.0> 1996-10-16 16:15:12
222
\01115 progress <0.17.0> 1996-10-16 16:16:14
223
\01114 progress <0.17.0> 1996-10-16 16:16:14
224
\01113 progress <0.17.0> 1996-10-16 16:16:14
225
\01112 progress <0.14.0> 1996-10-16 16:16:14
226
\01111 error <0.17.0> 1996-10-16 16:16:21
227
\01110 error <0.17.0> 1996-10-16 16:16:21
228
\0119 crash_report release_handler 1996-10-16 16:16:21
229
\0118 supervisor_report <0.17.0> 1996-10-16 16:16:21
230
\0117 progress <0.17.0> 1996-10-16 16:16:21
231
\0116 progress <0.17.0> 1996-10-16 16:16:36
232
\0115 progress <0.17.0> 1996-10-16 16:16:36
233
\0114 progress <0.17.0> 1996-10-16 16:16:36
234
\0113 progress <0.14.0> 1996-10-16 16:16:36
235
\0112 error <0.15.0> 1996-10-16 16:17:04
236
\0111 progress <0.14.0> 1996-10-16 16:17:09
242
<title>Show Reports</title>
243
<p>To show details of a specific report, use the function
244
<c>rb:show(Number)</c>:</p>
247
10> <input>rb:show(1).</input>
248
7> <input>rb:show(4).</input>
250
PROGRESS REPORT <0.20.0> 1996-10-16 16:16:36
251
===============================================================================
252
supervisor {local,sasl_sup}
255
{name,release_handler},
256
{mfa,{release_handler,start_link,[]}},
257
{restart_type,permanent},
264
CRASH REPORT <0.24.0> 1996-10-16 16:16:21
265
===============================================================================
268
registered_name release_handler
269
error_info {undef,{release_handler,mbj_func,[]}}
280
ancestors [sasl_sup,<0.18.0>]
282
links [<0.23.0>,<0.20.0>]
295
<title>Search the Reports</title>
296
<p>It is possible to show all reports which contain a common
297
pattern. Suppose a process crashes because it tries to call a
298
non-existing function <c>release_handler:mbj_func.</c> We could
299
then show reports as follows:</p>
302
12><input>rb:grep("mbj_func").</input>
303
Found match in report number 11
305
ERROR REPORT <0.24.0> 1996-10-16 16:16:21
306
===============================================================================
308
** undefined function: release_handler:mbj_func[] **
309
Found match in report number 10
311
ERROR REPORT <0.24.0> 1996-10-16 16:16:21
312
===============================================================================
314
** Generic server release_handler terminating
315
** Last message in was {unpack_release,hej}
316
** When Server state == {state,[],
317
"/home/dup/otp2/otp_beam_sunos5_p1g_7",
325
** Reason for termination ==
326
** {undef,{release_handler,mbj_func,[]}}
327
Found match in report number 9
329
CRASH REPORT <0.24.0> 1996-10-16 16:16:21
330
===============================================================================
333
registered_name release_handler
334
error_info {undef,{release_handler,mbj_func,[]}}
345
ancestors [sasl_sup,<0.18.0>]
347
links [<0.23.0>,<0.20.0>]
355
Found match in report number 8
357
SUPERVISOR REPORT <0.20.0> 1996-10-16 16:16:21
358
===============================================================================
359
Reporting supervisor {local,sasl_sup}
362
errorContext child_terminated
363
reason {undef,{release_handler,mbj_func,[]}}
366
start_function {release_handler,start_link,[]}
367
restart_type permanent
375
<title>Stop the Server</title>
376
<p>Stop the <c>rb_server</c> with the function
377
<c>rb:stop()</c>:</p>
380
13><input>rb:stop().</input>
added
removed
lib/sasl/doc/src/error_logging.xml
