observer: add wx version of crashdump_viewer

The old web base crashdump_viewer is now removed.

1 files changed, 345 insertions, 82 deletions

diff --git a/lib/observer/doc/src/crashdump_ug.xml b/lib/observer/doc/src/crashdump_ug.xml
index fd4405df09..d22fb4cc40 100644
--- a/lib/observer/doc/src/crashdump_ug.xml
+++ b/lib/observer/doc/src/crashdump_ug.xml
@@ -13,12 +13,11 @@
       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>
@@ -31,9 +30,9 @@
 
   <section>
     <title>Introduction</title>
-    <p>The Crashdump Viewer is an HTML based tool for browsing Erlang
-      crashdumps. Crashdump Viewer runs under the WebTool application.
-      </p>
+    <p>The Crashdump Viewer is a WxWidgets based tool for browsing
+    Erlang crashdumps.
+    </p>
   </section>
 
   <section>
@@ -42,93 +41,357 @@
     <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
-    WebTool, Crashdump Viewer and a web browser, and loads the given
-    file. The browser should then display a page named General
-    Information which shows a short summary of the information in
-    the crashdump.</p>
-
-    <p>The default browser is Internet Explorer on Windows, open on Mac OS X, 
-    or else Firefox. To use another browser, give the browser's start command
-    as the second argument to <c>cdv</c>. If the given browser name is
-    not known to Crashdump Viewer, the browser argument is executed as
-    a command with the start URL as the only argument.</p>
+    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>. This
-    will automatically start WebTool and display the web address where
-    WebTool can be found. See the documentation for the WebTool
-    application for further information about how to use WebTool.</p>
-
-    <p>Point your web browser to the address displayed, and you should
-      now see the start page of WebTool. At the top of the page, you
-      will see a link to "CrashDumpViewer". Click this link to get to
-      the start page for Crashdump Viewer. (Note that if webtool is on
-      localhost, you must configure your web browser to have direct
-      connection to the internet, or you must set no proxy for
-      localhost.)
-      </p>
-    <p>From the start page of Crashdump Viewer, push the "Load
-      Crashdump" button to load a crashdump into the tool. Then enter
-      the filename of the crashdump in the entry field and push the
-      "Ok" button. This will bring you to the General Information
-      page, i.e. the same page as the <c>cdv</c> script will open in
-      the browser.
-      </p>
-    <p>Crashdumps generated by OTP R9C and later are loaded directly
-      into the Crashdump Viewer, while dumps from earlier releases first
-      are translated by the Crashdump Translater. The Crashdump
-      Translater creates a new file with the same name as the original
-      crashdump, but with the extension <c>.translated</c>. If there is
-      no write access to the directory of the original file, you will be
-      asked to enter a new path and filename for the translated file.
-      </p>
+    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>Navigating</title>
-    <p>The lefthand frame contains a menu. Menu folders can be
-      expanded and collapsed by clicking the folder picture. When a menu
-      item is clicked, the item information is shown in the big
-      information frame. 
-      </p>
-    <p>The filename frame above the information frame shows the full
-      name of the currently viewed Erlang crashdump.
-      </p>
-    <p>To load a new crashdump, click the "Load New Crashdump" button
-      in the menu frame.
-      </p>
-    <p>The various information shown in the information frame will
-      contain links to process identifiers (PIDs) and port
-      identifiers. Clicking one of these links will take you to the
-      detailed information page for the process or port in question. Use
-      the "Back" button in your browser to get back to the
-      startingpoint. If the process or port resided on a remote node,
-      there will be no information available. Clicking the link will
-      then take you to the information about the remote node.
-      </p>
+    <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>Help</title>
-    <p>Further help on how to use the Crashdump Viewer tool can be
-      found in the tool's menu under 'Documentation':
-      </p>
-    <p>'Crashdump Viewer help' is a short document describing each
-      information page and any additional information that might occur,
-      compared to the raw dump described in 'How to interpret Erlang
-      crashdumps'.
-      </p>
-    <p>'How to interpret Erlang crashdumps' is a document from the
-      Erlang runtime system describing details in the raw
-      crashdumps. 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>
+    <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>
-</chapter>
 
+  <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>