path: root/lib/observer/doc/src/crashdump_ug.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    </legalnotice>

    <title>Crashdump Viewer</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>crashdump_ug.xml</file>
  </header>

  <section>
    <title>Introduction</title>
    <p>The Crashdump Viewer is a WxWidgets based tool for browsing
    Erlang crashdumps.
    </p>
  </section>

  <section>
    <title>Getting Started</title>

    <p>The easiest way to start Crashdump Viewer is to use
    shell script <c>cdv</c> with the full path to the
    Erlang crashdump as argument. The script is located in
    directory <c>priv</c> of the Observer application. This starts the
    Crashdump Viewer GUI and loads the specified file. If no filename is
    specified, a file dialog is opened where the file can be
    selected.</p>

    <p>Under Windows, the batch file <c>cdv.bat</c> can be used.</p>

    <p>Crashdump Viewer can also be started from
    an Erlang node by calling <seealso
    marker="crashdump_viewer#start/0">crashdump_viewer:start/0</seealso>
    or <seealso
    marker="crashdump_viewer#start/1">crashdump_viewer:start/1</seealso>.</p>
  </section>

  <section>
    <title>GUI</title>

    <p>The GUI main window is opened when Crashdump Viewer has loaded a
    crashdump. It contains a title bar, a menu bar,
    information tabs, and a status bar.</p>

    <p>The title bar shows the name of the currently loaded
    crashdump.</p>

    <p>The menu bar contains a <em>File</em> menu and a <em>Help</em>
    menu. From the <em>File</em> menu, a new crashdump can be loaded or 
    the tool can be terminated. From the <em>Help</em> menu, this User's Guide 
    and section "How to interpret the Erlang crash dumps" from the
    ERTS application can be opened. "How to interpret
    the Erlang crash dumps" describes the raw crashdumps in
    detail and includes information about each
    field in the information pages."How to interpret the Erlang crash dumps" 
    is also available in the OTP online documentation.</p>

    <p>The status bar at the bottom of the window shows a warning
    if the currently loaded dump is truncated.</p>

    <p>The center area of the main window contains the information
    tabs. Each tab displays information about a specific item or a
    list of items. Select a tab by clicking the tab title.</p>

    <p>From tabs displaying lists of items, for example, the
    <em>Processes</em> tab or the <em>Ports</em> tab, a new window with 
    more information can be opened by double-clicking a row or by right-
    clicking the row and selecting an item from the drop-down
    menu. The new window is called a detail window. Detail windows can
    be opened for processes, ports, nodes, and modules.</p>

    <p>The information shown in a detail window can contain
    links to processes or ports. Clicking one of these links opens
    the detail window for the process or port in question. If the
    process or port resides on a remote node, no
    information is available. Clicking the link then displays a dialog
    where you can choose to open the detail window for the
    remote node.
    </p>

    <p>Some tabs contain a left-hand menu where subitems of
    the information area can be selected. Click one of the
    rows, and the information is displayed in the right-hand
    information area.</p>
  </section>

  <section>
    <title>Tab Content</title>

    <p>Each tab in the main window contains an information
    page. If no information is found for an item, the page is
    empty. The reason for not finding information about an item
    can be the following:</p>
    <list type="bulleted">
       <item>It is a dump from an old OTP release in which this item was not written.</item>
       <item>The item was not present in the system at the point of failure.</item>
       <item>The dump is truncated. In this case, a warning is displayed in the
       status bar of the main window.</item>
     </list>

    <p></p>

    <p>Even if some information about an item exists, there can be
    empty fields if the dump originates from an old OTP release.</p>

    <p>The value <c>-1</c> in any field means "unknown", and in most
    cases it means that the dump was truncated somewhere around this
    field.</p>

    <p>The following sections describe some of the fields in the
    information tabs. These are fields that do not exist
    in the raw crashdump, or in some way differ from the fields in
    the raw crashdump. For details about other fields, see
    the 
    <seealso marker="erts:users_guide">ERTS User's Guide</seealso>, section
    "How to interpret the Erlang crash dumps". That section can also
    be opened from the <em>Help</em> menu in the main window.
    There are also links from the following sections to related information 
    in "How to interpret the Erlang crash dumps".</p>
  </section>

  <section>
    <marker id="general_info"/>
    <title>General Tab</title>

    <p>Tab <em>General</em> shows a short overview
    of the dump.</p>

    <p>The following fields are not described in the ERTS
    User's Guide:</p>

    <taglist>
      <tag><c>Crashdump created on</c></tag>
      <item><p>Time of failure.</p></item>

      <tag><c>Memory allocated</c></tag>
      <item><p>The total number of bytes allocated, equivalent to
      <c>c:memory(total)</c>.</p></item>

      <tag><c>Memory maximum</c></tag>
      <item><p>The maximum number of bytes that has been allocated during
      the lifetime of the originating node. This is only shown if
      the Erlang runtime system is run instrumented.</p></item>

      <tag><c>Atoms</c></tag>
      <item><p>If available in the dump, this is the total number of
      atoms in the atom table. If the size of the atom table is
      unavailable, the number of atoms visible in the dump is
      displayed.</p></item>

      <tag><c>Processes</c></tag>
      <item><p>The number of processes visible in the dump.</p></item>

      <tag><c>ETS tables</c></tag>
      <item><p>The number of ETS tables visible in the dump.</p></item>

      <tag><c>Funs</c></tag>
      <item><p>The number of funs visible in the dump.</p></item>
    </taglist>

    <p>For details, see
      <seealso marker="erts:crash_dump#general_info">General Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="processes"/>
    <title>Processes Tab</title>

    <p>Tab <em>Processes</em> shows a list of all processes
    found in the crashdump, including brief information about
    each process. By default, the processes are sorted by their
    pids. To sort by another topic, click the desired column heading.</p>

    <p>Column <em>Memory</em> shows the 'Memory' field that was
    added to crashdumps in Erlang/OTP R16B01. This is the total amount of memory
    used by the process. For crashdumps from earlier releases, this
    column shows the 'Stack+heap' field. The value is always in bytes.</p>

    <p>To view detailed information about a specific process, double-
    click the row in the list, or right-click the row and select
    <em>Properties for &lt;pid&gt;</em>.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#processes">Process Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="ports"/>
    <title>Ports Tab</title>

    <p>Tab <em>Ports</em> is similar to the <em>Processes</em>
    tab, except it lists all ports found in the crashdump.</p>

    <p>To view more details about a specific port, double-click the row
    or right-click it and select <em>Properties for &lt;port&gt;</em>. From
    the right-click menu, you can also select <em>Properties for
    &lt;pid&gt;</em>, where <c>&lt;pid&gt;</c> is the process connected to the
    port.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#ports">Port Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="ets_tables"/><marker id="internal_ets_tables"/>
    <title>ETS Tables Tab</title>

    <p>Tab <em>ETS Tables</em> shows all ETS table information
    found in the dump. <em>Id</em> is the same as the 'Table' field
    in the raw crashdump. <em>Memory</em> is the 'Words' field from the
    raw crashdump translated into bytes. For tree tables, there is
    no value in the 'Objects' field.</p>

    <p>To open the detailed information page about the table, double-
    click, or right-click the row and select <em>Properties for
    'Identifier'</em>.</p>

    <p>To open the detailed information page about the owner process
    of an ETS table, right-click the row and select <em>Properties for
    &lt;pid&gt;</em>.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#ets_tables">ETS Tables</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="timers"/>
    <title>Timers Tab</title>

    <p>Tab <em>Timers</em> shows all timer information found in
    the dump.</p>

    <p>To open the detailed information page about the owner process
    of a timer, right-click the row and select <em>Properties for
    &lt;pid&gt;</em>.</p>

    <p>Double-clicking a row in the <em>Timers</em> tab has no effect.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#timers">Timers</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="schedulers"/>
    <title>Schedulers Tab</title>

    <p>Tab <em>Schedulers</em> shows all scheduler information
    found in the dump.</p>

    <p>To open the detailed information page about the scheduler,
    double-click, or right-click the row and select <em>Properties for
    'Identifier'</em>.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#scheduler">Scheduler Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="funs"/>
    <title>Funs Tab</title>

    <p>Tab <em>Funs</em> shows all fun information found in the
    dump.</p>

    <p>To open the detailed information page about the module to which
    the fun belongs, right-click the row and select <em>Properties for
    &lt;mod&gt;</em>.</p>

    <p>Double-clicking a row in the <em>Funs</em> tab has no effect.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#funs">Fun Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="atoms"/>
    <title>Atoms Tab</title>

    <p>Tab <em>Atoms</em> lists all atoms found in the dump. By
    default the atoms are sorted in creation order from first to
    last. This is opposite of the raw crashdump where atoms are listed
    from last to first, meaning that if the dump was truncated in the
    middle of the atom list, only the last created atoms are visible
    in the <em>Atoms</em> tab.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#atoms">Atoms</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="distribution_info"/>
    <title>Nodes Tab</title>

    <p>Tab <em>Nodes</em> shows a list of all external Erlang
    nodes that are referenced from the crashdump.</p>

    <p>If the page is empty, it means either of the following:</p>
    <list type="bulleted">
       <item>The crashed node is not distributed.</item>
       <item>The crashed node is distributed but has no references to other nodes.</item>
       <item>The dump is truncated.</item>
     </list>

    <p>If the node is distributed, all referenced nodes are
    visible. Column <em>Connection type</em> shows if the node
    is visible, hidden, or not connected. Visible nodes are alive nodes
    with a living connection to the originating node. Hidden nodes are
    the same as visible nodes, except they are started with flag
    <c>-hidden</c>. Not connected nodes are nodes that are not
    connected to the originating node anymore, but references
    (that is, process or port identifiers) exist.</p>

    <p>To see more detailed information about a node, double-click the
    row, or right-click the row and select <em>Properties for node
    &lt;node&gt;</em>. From the right-click menu, you can also select
    <em>Properties for &lt;port&gt;</em>, to open the detailed information
    window for the controlling port.</p>

    <p>In the detailed information window for a node, any existing
    links and monitors between processes on the originating node and
    the connected node are displayed. <em>Extra Info</em> can contain
    debug information (that is, special information written if the
    emulator is debug-compiled) or error information.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#distribution_info">Distribution Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="loaded_modules"/>
    <title>Modules Tab</title>

    <p>Tab <em>Modules</em> lists all modules loaded
    on the originating node, and the current code size. If old
    code exists, the old size is also shown.</p>

    <p>To view detailed information about a specific module, double-
    click the row, or right-click it and select <em>Properties for
    &lt;mod&gt;</em>.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#loaded_modules">Loaded Module Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>

  <section>
    <marker id="memory"/>
    <title>Memory Tab</title>

    <p>Tab <em>Memory</em> shows memory and allocator
    information. From the left-hand menu you can select the following:</p>

      <taglist>
	<tag><em>Memory</em></tag>
	<item><p>See
	<seealso marker="erts:crash_dump#memory">Memory Information</seealso>
	in section "How to Interpret the Erlang Crash Dumps" in ERTS.</p></item>

	<tag><em>Allocator Summary</em></tag>
	<item><p>This page presents a summary of values from all allocators underneath it.</p></item>

	<tag><em>&lt;Allocator&gt;</em></tag>
	<item><p>One entry per allocator. See
	<seealso marker="erts:crash_dump#allocator">Allocator</seealso>
	in section "How to Interpret the Erlang Crash Dumps" in ERTS.</p></item>

	<tag><em>Allocated Areas</em></tag>
	<item><p>See
	<seealso marker="erts:crash_dump#allocated_areas">Allocated Areas</seealso>
	in section "How to Interpret the Erlang Crash Dumps" in ERTS.</p></item>

      </taglist>
  </section>

  <section>
    <marker id="internal_tables"/>
    <title>Internal Tables Tab</title>

    <p>On tab <em>Internal Tables</em> you can from the
    left-hand menu select <em>Hash Tables</em>, <em>Index Tables</em>, 
    or <em>Internal ETS Tables</em>.</p>

    <p>For details, see
      <seealso marker="erts:crash_dump#internal_tables">Internal Table Information</seealso>
      in section "How to Interpret the Erlang Crash Dumps" in ERTS.
    </p>
  </section>
</chapter>