diff options
Diffstat (limited to 'lib/sasl/doc/src/error_logging.xml')
| -rw-r--r-- | lib/sasl/doc/src/error_logging.xml | 385 |
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öberg</prepared> + <responsible>Bjarne Dä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 === + <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> + </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 <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> + </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 <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> + </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 <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> + </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> + |