path: root/lib/pman/doc/src/pman_chapter.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1996</year><year>2012</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>Pman</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>pman_chapter.xml</file>
  </header>
  <marker id="here"></marker>

  <section>
    <title>Introduction</title>
    <warning>
      <p>
	The Pman application has been superseded by the Observer application.
	Pman will be removed in R16.
      </p>
    </warning>
    <p>The process manager Pman is a tool for viewing processes executing
      locally or on remote nodes. Its main purpose is to locate
      erroneous code by inspecting the state of the processes and by tracing
      events. Bottlenecks, unread messages, and bad memory handling are 
      some of the problems that can be solved with Pman.</p>
    <p>Processes may be inspected individually in a process trace
      window. There the user may dynamically follow the execution of a
      process by getting trace output for sent and received messages
      as well as for called functions and some other process
      events. Information about source code modules executed by the
      processes is also accessible. Note that Pman has some effect on
      the real time behavior of a running system.</p>
  </section>

  <section>
    <title>Getting Started with Pman</title>
    <p>Start Pman by calling <c>pman:start()</c>. It will start
      the <seealso marker="#main_win">Main Window</seealso>, showing an
      overview of all processes running at the current node.</p>
    <p>To trace a certain process, select it by clicking on its line and
      then chose Trace-&gt;Selected Process, or simply double-click it. This
      will open a <seealso marker="#trace_win">Trace Window</seealso>.
      In the Trace Window, there is some information about the process
      and traced events are added dynamically.</p>
    <p>Which events to trace are selected in
      the <seealso marker="#options_win">Options Window</seealso> which
      is opened by choosing File-&gt;Options... in the Main Window or in a
      Trace Window. Currently supported trace events are message sending,
      message receiving, function calls and process events.</p>
    <p>It is possible to by-pass the Main Window and open a Trace
      Window directly for the process <c>Pid</c> by calling
      <c>pman:proc(Pid)</c>.</p>
  </section>

  <section>
    <marker id="main_win"></marker>
    <title>The Main Window</title>
    <p>The Main Window shows all processes running at the displayed node.
      The window is automatically updated every 5 seconds.
      Select which node to display in the window by choosing the node name
      from the Nodes menu.</p>
    <image file="main_window.gif">
      <icaption>The Main Window.</icaption>
    </image>
    <p>A process can be selected by clicking on its line. The selected
      process is highlighted. Use the arrow keys to move up and down in
      the process overview.</p>
    <p>The following information is displayed for each process:</p>
    <list type="bulleted">
      <item>Pid - process identifier.</item>
      <item>Current Function - the function (<c>Module:Function/Arity</c>)
       the process is currently executing.</item>
      <item>Name - registered name of the process, if any.</item>
      <item>Msgs - number of messages in the process' mailbox.</item>
      <item>Reds - number of reductions performed. Gives a rough estimate
       of the process' work load.</item>
      <item>Size - estimated size of the process, in words, calculated by
       adding the stack size and the heap size.</item>
    </list>
    <p>At the bottom of the window the following functions and
      information can be found:</p>
    <taglist>
      <tag><em>Hide System Processes</em></tag>
      <item>This check button controls the display of what Pman consider
      <em>system processes</em>, that is, processes Pman knows are part
       of Erlang/OTP rather than the user's application.
       If the button is selected, these system processes will not be
       shown.</item>
      <tag><em>Auto-Hide New</em></tag>
      <item>This check button controls the treatment of newly created
       processes. If it is selected, new processes will not be shown.</item>
      <tag><em># Hidden</em></tag>
      <item>This label displays the number of processes currently
       executing that are not shown in the process overview.</item>
    </taglist>

    <section>
      <title>The File Menu</title>
      <taglist>
        <tag><em>Options...</em></tag>
        <item>Open the <seealso marker="#options_win">Options Window</seealso>
         which allows the user to set the trace options to use.</item>
        <tag><em>Save Options</em></tag>
        <item>Save the options set using the Options Window. The options are
         stored to the file <c>HOME/.erlang_tools/pman.opts</c>, where
        <c>HOME</c> is the user's home directory, and are automatically
         loaded the next time Pman is started.</item>
        <tag><em>Exit</em></tag>
        <item>Stop Pman.</item>
      </taglist>
    </section>

    <section>
      <title>The View Menu</title>
      <p>This menu mainly contains buttons for controlling what to
        display in the Main Window. Note that the View Menu overrides
        the settings of the check buttons (Hide System processes, Auto-Hide
        new) in the Main Window.</p>
      <taglist>
        <tag><em>Hide All Processes</em></tag>
        <item>Hide all processes.</item>
        <tag><em>Hide Modules...</em></tag>
        <item>Opens a dialog window with all loaded modules. If the user
         selects a window and clicks OK, the process overview will not
         show any processes running code from those modules.</item>
        <tag><em>Hide Selected Processs</em></tag>
        <item>Hide the selected process.</item>
        <tag><em>Module Info...</em></tag>
        <item>Given a selected process currently executing a function in
         the module <c>Module</c>, this menu button opens a window
         showing information about the module as returned from
        <c>Module:module_info()</c>.</item>
        <tag><em>Refresh</em></tag>
        <item>Updates the process overview.</item>
        <tag><em>Show All Processes</em></tag>
        <item>Show all processes, except system processes and/or new
         processes if <em>Hide System Processes</em> and/or
        <em>Auto-Hide New</em> is selected.</item>
        <tag><em>Show Processes...</em></tag>
        <item>Opens a dialog window with all hidden processes. If
         the user selects a process and clicks OK, the process
         overview will show that process.</item>
      </taglist>
    </section>

    <section>
      <title>The Trace Menu</title>
      <taglist>
        <tag><em>Kill</em></tag>
        <item>Terminates the selected process by calling
        <c>exit(Pid,kill)</c>.</item>
        <tag><em>Trace Selected Process</em></tag>
        <item>Opens a Trace Window for the selected process. Tracing
         will start immediately with the default trace flags set from
         the Main Window.</item>
        <tag><em>Shell Process</em></tag>
        <item>Opens a Trace Window for the shell process of node Pman
         was started at (not the displayed node). If the shell process
         dies, the opened Trace Window will find the pid of
         the automatically started new shell process, and continue to
         trace that process.</item>
      </taglist>
    </section>

    <section>
      <title>The Nodes Menu</title>
      <p>The Nodes menu contains one entry for each known node.
        By selecting a node from the Nodes menu, the process overview
        window will change its view, and display the processes running
        on that node.</p>
    </section>

    <section>
      <title>The Help Menu</title>
      <taglist>
        <tag><em>Help</em></tag>
        <item>Selecting Help from the Help menu will cause the HTML
         version of the Pman User's Guide (this document) to be
         displayed. Currently this function requires Netscape to be up
         and running.</item>
      </taglist>
    </section>
  </section>

  <section>
    <marker id="trace_win"></marker>
    <title>The Trace Window</title>
    <p>A Trace Window outputs trace information for a traced process.
      A Trace Window automatically uses the trace options set in
      the Main Window, but it is also possible to change the options for
      each Trace Window individually.</p>
    <image file="trace.gif">
      <icaption>The Trace Window.</icaption>
    </image>
    <p>There is no limit to how many Trace Windows can be open at the same
      time. However, notice that if more processes are traced,
      the performance degradation of the system will be more noticeable.</p>
    <p>The following information is displayed, where applicable:</p>
    <list type="bulleted">
      <item>initial call - the function (<c>Module:Function/Arity</c>)
       the process started executing in.</item>
      <item>current function - the function (<c>Module:Function/Arity</c>)
       the process is currently executing.</item>
      <item>messages - the messages in the mailbox.</item>
      <item>dictionary - the contents of the process dictionary.</item>
      <item>heap size - heap size in words.</item>
      <item>stack size - stack size in words.</item>
      <item>reductions - number of reductions performed. Gives a rough
       estimate of the process' work load.</item>
      <item>links - list of pids the process is linked to.</item>
      <item>trap_exit - <c>true</c> if the process trap exit signals,
      <c>false</c> otherwise.</item>
    </list>
    <p>In the Trace Window, trace output is continuously added. First in
      each trace message is the pid of the traced process.
      Note that if the inheritance flags for tracing are set, the trace
      output for the spawned/linked processes will be shown in the same
      window as the spawning/linking process.</p>
    <p>Each trace message also has a mnemonic tag:</p>
    <taglist>
      <tag><em>!</em></tag>
      <item>This tag indicates that a message has been sent. Following
       the <c>To:</c> tag will be a pid/name of the receiver. Next,
       following the <c>Msg:</c> tag will be the sent message.</item>
      <tag><em>rec</em></tag>
      <item>This tag indicates that a message has been received.
       Following this will be the received message.</item>
      <tag><em>call</em></tag>
      <item>This tag indicates a call to a function. Following this will be
       the actual call, with all the arguments.</item>
      <tag><em>link</em></tag>
      <item>This tag indicates that a link between the traced process and
       another process has been created. Following this will be the pid
       of the other process.</item>
      <tag><em>spawn</em></tag>
      <item>This tag indicates that the traced process has spawned another
       process. Following this will be the pid of the spawned process.</item>
      <tag><em>exit</em></tag>
      <item>This tag indicates that traced process has exited. Following
       this will be the exit reason.</item>
    </taglist>

    <section>
      <title>The File Menu</title>
      <taglist>
        <tag><em>Options...</em></tag>
        <item>Opens the <seealso marker="#options_win">Options Window</seealso>
         which allows the user to set the trace options to use for this
         specific Trace Window.</item>
        <tag><em>Save Buffer...</em></tag>
        <item>Opens a dialog that prompts the user for a file name to
         save the current Trace Window contents in.</item>
        <tag><em>Close</em></tag>
        <item>Stops tracing of the process, and closes the Trace Window.</item>
      </taglist>
    </section>

    <section>
      <title>The View Menu</title>
      <taglist>
        <tag><em>Clear Buffer</em></tag>
        <item>Clears the contents of the Trace Window.</item>
        <tag><em>Module Info</em></tag>
        <item>Opens a window showing information about the module
         the process is currently executing code from, as returned from
        <c>Module:module_info()</c>.</item>
      </taglist>
    </section>

    <section>
      <title>The Trace Menu</title>
      <taglist>
        <tag><em>All Linked Processes</em></tag>
        <item>Opens a Trace Window for each of the processes linked to the
         process being traced in the current Trace Window.</item>
        <tag><em>Linked Process -></em></tag>
        <item>The Linked Process submenu has one entry for each process
         linked to the process being traced in the current Trace Window.
         Select one of the processes to open a new Trace Window for that
         process.</item>
        <tag><em>Kill</em></tag>
        <item>Terminates the process being traced in the current Trace
         Window by calling <c>exit(Pid,kill)</c>.</item>
      </taglist>
    </section>

    <section>
      <title>The Help Menu</title>
      <taglist>
        <tag><em>Help</em></tag>
        <item>Selecting Help from the Help menu will cause the HTML version
         of the Pman User's Guide (this document) to be displayed.
         Currently this function requires Netscape to be up and running.</item>
      </taglist>
    </section>
  </section>

  <section>
    <marker id="options_win"></marker>
    <title>The Options Window</title>
    <p>The Options Window allows the user to specify the amount of output,
      and the destination of output for traced processes.</p>
    <image file="options.gif">
      <icaption>The Options Window.</icaption>
    </image>
    <p>In the upper left corner of the Options Window, there are check
      buttons for determining what to output in the Trace Window:</p>
    <taglist>
      <tag><em>Trace send</em></tag>
      <item>Select this check button to display information about sent
       messages.</item>
      <tag><em>Trace receive</em></tag>
      <item>Select this check button to display information about received
       messages.</item>
      <tag><em>Trace functions</em></tag>
      <item>Select this check button to display information about
       function calls.</item>
      <tag><em>Trace events</em></tag>
      <item>Select this check button to display information about process
       events, such as spawn, link and exit.</item>
    </taglist>
    <p>In the upper right corner of the dialog, there are options for
      controlling the behaviour of spawned or linked processes:</p>
    <taglist>
      <tag><em>Inherit on spawn</em></tag>
      <item>
        <p>The user may select if spawned processes shall also be traced.
          And if so, if all spawned processes should be traced, or just
          the first spawned process.</p>
        <p>If a spawned process is traced, it will get the same trace
          options that are set for the spawning process. And the output
          will be shown in the same Trace Window as that of the spawning
          process.</p>
        <p>.</p>
      </item>
      <tag><em>Inherit on link</em></tag>
      <item>
        <p>The user may select if a process that is being linked to
          shall be traced. And if so, if all linked processes shall be
          traced, or just the first one linked to.</p>
        <p>If a linked process is traced, it will get the same trace
          options that are set for the linking process. And the output
          will be shown in the same Trace Window as that of the linked
          process.</p>
      </item>
    </taglist>
    <p>In the lower part of the Options Dialog, the user may select
      whether the trace information shall be output to a file, or appear in
      the trace window.</p>
    <p>Sending trace information to a file is more efficient than displaying
      it in the Trace Window. Furthermore, if the amount of trace data is
      large, it will not be lost if tracing to a file. The trace information
      in the Trace Window has an upper limit (approx. 10,000 lines), after
      which the output buffer will be cleared.</p>
  </section>
</chapter>