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>2013</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>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 the
    provided shell script named <c>cdv</c> with the full path to the
    erlang crashdump as an argument. The script can be found in the
    priv directory of the <c>observer</c> application. This starts the
    Crashdump Viewer GUI and loads the given file. If no file name is
    given, a file dialog will be opened where the file can be
    selected.</p>

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

    <p>It is also possible to start the Crashdump Viewer from within
    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>The graphical interface</title>

    <p>The main window is opened when Crashdump Viewer has loaded a
    crashdump. It contains a title bar, a menu bar, a number of
    information panels 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 File menu a new crashdump can be loaded or the tool
    can be terminated. From the Help menu this user's guide and the
    chapter "How to interpret the Erlang crash dumps" from the user's
    guide for Erlang runtime system can be opened. "How to interpret
    the Erlang crash dumps" describes the raw crashdumps in
    detail. Here you will also find information about each single
    field in the different information pages. This document can also
    be found directly in the OTP online documentation, via the Erlang
    runtime system user's guide.</p>

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

    <p>The centre area of the main window contains the information
    panels. Each panel displays information about a specific item or a
    list of items. A panel is selected by clicking the title of the
    tab.</p>

    <p>From panels that display lists of items, for example the
    Processes- or the Ports panel, a new window with further
    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 various information shown in a detail window might contain
    links to processes or ports. Clicking one of these links will open
    the detail window for the process or port in question. If the
    process or port resided on a remote node, there will be no
    information available. Clicking the link will then pop up a dialog
    where you can choose whether to open the detail window for the
    remote node or not.
    </p>

    <p>Some of the panels contain a left hand menu where sub items of
    the panel's information area can be selected. Click on one of the
    rows, and the information will be displayed in the right hand
    information area.</p>
  </section>

  <section>
    <title>Data content</title>

    <p>Each panel in the main window contains an information
    page. If no information is found for an item, the page will be
    empty. The reason for not finding any information about an item
    can be that the dump is truncated, that it is a dump from an old
    OTP release in which this item was not written or that the item
    simply wasn't present in the system at the point of failure.</p>

    <p>If the dump was truncated, a warning is displayed in the
    status bar of the main window.</p>

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

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

    <p>The sections below describe some of the fields in the
    different information panels. These are fields that do not exist
    in the raw crashdump, or in some way differ from the fields in
    the raw crashdump. Details about other fields can be found in
    the user's guide for the Erlang runtime system, in the chapter
    "How to interpret the Erlang crash dumps". That chapter can also
    be opened from the Help menu in the Crashdump Viewer's main
    window, and there are also direct links from the specific
    sections below to related information in "How to interpret the
    Erlang crash dumps".</p>
  </section>

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

    <p>The <em>General information</em> panel shows a short overview
    of the dump.</p>

    <p>The following fields are not described in the Erlang runtime
    system user's guide:</p>

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

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

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

      <tag><em>Atoms</em></tag>
      <item>If available in the dump, this is the total number of
      atoms in the atom table. If the size of the atom table is not
      available, the number of atoms visible in the dump is
      presented.</item>

      <tag><em>Processes, ETS tables and Funs</em></tag>
      <item>The number of processes, ETS tables and funs visible in
      the dump.</item>
    </taglist>

    <p>
      <seealso marker="erts:crash_dump#general_info">More...</seealso>
    </p>
  </section>

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

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

    <p>The <em>Memory</em> column shows the 'Memory' field which was
    added to crashdumps in 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 shown 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
    "Properties for &lt;pid&gt;".</p>

    <p>
      <seealso marker="erts:crash_dump#processes">More...</seealso>
    </p>
  </section>

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

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

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

    <p>
      <seealso marker="erts:crash_dump#ports">
      More...</seealso>
    </p>
  </section>

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

    <p>The <em>ETS Tables</em> panel shows all ETS table information
    found in the dump. The 'Id' is the same as the 'Table' field found
    in the raw crashdump, and 'Memory' is the 'Words' field from the
    raw crashdump translated into bytes. 'Type' is the type of table,
    and it can be either "hash" or "tree". For tree tables there will
    be no value in the 'Bucket' field.</p>

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

    <p>Double clicking a row in the ETS Tables panel has no
    effect.</p>

    <p>From the left hand menu you can also select to see internal ETS
    tables.</p>

    <p>
      <seealso marker="erts:crash_dump#ets_tables">
      More...</seealso>
    </p>
  </section>

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

    <p>The <em>Timers</em> panel 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 "Properties for
    &lt;pid&gt;".</p>

    <p>Double clicking a row in the Timers panel has no effect.</p>

    <p>
      <seealso marker="erts:crash_dump#timers">More...</seealso>
    </p>
  </section>

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

    <p>The <em>Funs</em> panel 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 "Properties for
    &lt;mod&gt;".</p>

    <p>Double clicking a row in the Funs panel has no effect.</p>

    <p>
      <seealso marker="erts:crash_dump#funs">More...</seealso>
    </p>
  </section>

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

    <p>The <em>Atoms</em> panel 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 will be seen
    in the <em>Atoms</em> panel.</p>

    <p>
      <seealso marker="erts:crash_dump#atoms">More...</seealso>
    </p>
  </section>

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

    <p>The <em>Nodes</em> panel shows a list of all external erlang
    nodes which are referenced from the crashdump.</p>

    <p>If the page is empty it either means that the crashed node was
    not distributed, that it was distributed but had no references to
    other nodes or that the dump was truncated.</p>

    <p>If the node was distributed, all referenced nodes are
    shown. The column named <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 the
    <c>-hidden</c> flag. Not connected nodes are nodes that are not
    connected to the originating node anymore, but references
    (i.e. 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 "Properties for node
    &lt;node&gt;". From the right click menu you can also select
    "Properties for &lt;port&gt;", to open the detailed information
    window for the controlling port.</p>

    <p>In the detailed information window for a node, any exsisting
    links and monitors between processes on the originating node and
    the connected node are shown. <em>Extra Info</em> may contain
    debug information (i.e. special information written if the
    emulator is debug compiled) or error information.</p>

    <p>
      <seealso marker="erts:crash_dump#distribution_info">
      More...</seealso>
    </p>
  </section>

  <section>
    <marker id="loaded_modules"/>
    <title>Loaded modules</title>

    <p>The <em>Modules</em> panel lists all modules that were loaded
    on the originating node, and the current size of the code. If old
    code exsits, the old size is also shown.</p>

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

    <p>
      <seealso marker="erts:crash_dump#loaded_modules">
      More...</seealso>
    </p>
  </section>

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

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

    <p>
      <list>

	<item><em>Memory</em> <seealso
	marker="erts:crash_dump#memory">More...</seealso></item>

	<item><em>Allocator Summary</em> - this page presents a
	summary of values from all allocators below.</item>

	<item><em>&lt;Allocator&gt;</em> - one entry per allocator
	<seealso
	marker="erts:crash_dump#allocator">More...</seealso></item>

	<item><em>Allocated Areas</em> <seealso
	marker="erts:crash_dump#allocated_areas">More...</seealso></item>

      </list>
    </p>
  </section>

  <section>
    <marker id="internal_tables"/>
    <title>Internal tables</title>

    <p>On the <em>Internal Tables</em> panel you can choose from the
    left hand menu to see hash tables or index tables.</p>

    <p>
      <seealso marker="erts:crash_dump#internal_tables">More...</seealso>
    </p>
  </section>
</chapter>