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

<chapter>
  <header>
    <copyright>
      <year>2002</year><year>2021</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>Erlang Top</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>etop_ug.xml</file>
  </header>

  <section>
    <title>Introduction</title>
    <p>Erlang Top, <c>etop</c>, is a tool for presenting information
      about Erlang processes similar to the information presented by
      <c>top</c> in UNIX.
      </p>
  </section>

 <section>
    <title>Getting Started</title>
    <p>Start Erlang Top in either of the following ways:</p>
      <list type="bulleted">
	<item>Use script <c>etop</c>.</item>
	<item>Use batch file <c>etop.bat</c>, for example, 
	<c>etop -node tiger@durin</c>.</item>
      </list>
  </section>

  <section>
    <title>Output</title>
    <p>The output from Erlang Top is as follows:</p>
    <code type="none"><![CDATA[
========================================================================================
 tiger@durin                                                               13:40:32
 Load:  cpu         0               Memory:  total        1997    binary         33
        procs     197                        processes       0    code          173
        runq      135                        atom         1002    ets            95

Pid            Name or Initial Func    Time    Reds  Memory    MsgQ Current Function
----------------------------------------------------------------------------------------
<127.23.0>     code_server                0   59585   78064       0 gen_server:loop/6   
<127.21.0>     file_server_2              0   36380   44276       0 gen_server:loop/6   
<127.2.0>      erl_prim_loader            0   27962    3740       0 erl_prim_loader:loop
<127.9.0>      kernel_sup                 0    6998    4676       0 gen_server:loop/6   
<127.17.0>     net_kernel                62    6018    3136       0 gen_server:loop/6   
<127.0.0>      init                       0    4156    4352       0 init:loop/1         
<127.16.0>     auth                       0    1765    1264       0 gen_server:loop/6   
<127.18.0>     inet_tcp_dist:accept       0     660    1416       0 prim_inet:accept0/2 
<127.5.0>      application_controll       0     569    6756       0 gen_server:loop/6   
<127.137.0>    net_kernel:do_spawn_       0     553    5840       0 dbg:do_relay_1/1    
========================================================================================
    ]]></code>
    <p>The header includes some system information:
      </p>
    <taglist>
      <tag><c>Load</c></tag>
      <item>
	<taglist>
       <tag><c>cpu</c></tag>
       <item><p><c>Runtime/Wallclock</c>, that is, the percentage of time 
       where the node has been active.</p></item>
       <tag><c>procs</c></tag>
       <item><p>The number of processes on the node.</p></item>
       <tag><c>runq</c></tag>
       <item><p>The number of processes that are ready to run.</p></item>
	</taglist>
      </item>
      <tag><c>Memory</c></tag>
      <item><p>The memory allocated by the node in kilobytes.</p></item>
    </taglist>
    <p>For each process the following information is presented:
      </p>
    <taglist>
      <tag><c>Time</c></tag>
      <item><p>The runtime for the process, that is, the time that the process 
      has been scheduled in.</p></item>
      <tag><c>Reds</c></tag>
      <item><p>The number of reductions executed on the process.</p></item>
      <tag><c>Memory</c></tag>
      <item><p>The size of the process in bytes, obtained by a
       call to <c>process_info(Pid,memory)</c>.</p></item>
      <tag><c>MsgQ</c></tag>
      <item><p>The length of the message queue for the process.</p></item>
    </taglist>
    <note>
      <p><em>Time</em> and <em>Reds</em> can be presented as
        accumulated values or as values since the last update.</p>
    </note>
  </section>

   <section>
    <title>Configuration</title>
    <p>All configuration parameters can be set at start by adding
      <c>-OptName Value</c> to the command line, for example:</p> 
      <pre>
% <input>etop -node tiger@durin -setcookie mycookie -lines 15</input></pre>
    
    <p>A list of all valid Erlang Top configuration parameters is available in
      module <seeerl marker="etop"><c>etop</c></seeerl>.
      </p>

      <p>The parameters <c>lines</c>, <c>interval</c>, <c>accumulate</c>,
      and <c>sort</c> can be changed during runtime with function 
      <seemfa marker="etop#config/2"><c>etop:config/2</c></seemfa>.
      </p>
      <p><em>Example:</em></p>
      <p>Change configuration parameter <c>lines</c> with text-based presentation. 
      Before the change, 10 lines are presented as follows:</p>
         <code type="none"><![CDATA[
========================================================================================
 tiger@durin                                                               10:12:39
 Load:  cpu         0               Memory:  total        1858    binary         33
        procs     191                        processes       0    code          173
        runq        2                        atom         1002    ets            95

Pid            Name or Initial Func    Time    Reds  Memory    MsgQ Current Function
----------------------------------------------------------------------------------------
<127.23.0>     code_server                0   60350   71176       0 gen_server:loop/6   
<127.21.0>     file_server_2              0   36380   44276       0 gen_server:loop/6   
<127.2.0>      erl_prim_loader            0   27962    3740       0 erl_prim_loader:loop
<127.17.0>     net_kernel                 0   13808    3916       0 gen_server:loop/6   
<127.9.0>      kernel_sup                 0    6998    4676       0 gen_server:loop/6   
<127.0.0>      init                       0    4156    4352       0 init:loop/1         
<127.18.0>     inet_tcp_dist:accept       0    2196    1416       0 prim_inet:accept0/2 
<127.16.0>     auth                       0    1893    1264       0 gen_server:loop/6   
<127.43.0>     ddll_server                0     582    3744       0 gen_server:loop/6   
<127.5.0>      application_controll       0     569    6756       0 gen_server:loop/6   
========================================================================================      ]]></code>
      <p>Function <c>etop:config/2</c> is called to change the number of showed 
      lines to 5:</p>

	 <pre>
> <input>etop:config(lines,5).</input>
ok</pre>

      <p>After the change, 5 lines are presented as follows:</p>
      <code type="none"><![CDATA[
(etop@durin)2> 
========================================================================================
 tiger@durin                                                               10:12:44
 Load:  cpu         0               Memory:  total        1859    binary         33
        procs     192                        processes       0    code          173
        runq        2                        atom         1002    ets            95

Pid            Name or Initial Func    Time    Reds  Memory    MsgQ Current Function
----------------------------------------------------------------------------------------
<127.17.0>     net_kernel               183      70    4092       0 gen_server:loop/6   
<127.335.0>    inet_tcp_dist:do_acc     141      22    1856       0 dist_util:con_loop/9
<127.19.0>     net_kernel:ticker/2      155       6    1244       0 net_kernel:ticker1/2
<127.341.0>    net_kernel:do_spawn_       0       0    5840       0 dbg:do_relay_1/1    
<127.43.0>     ddll_server                0       0    3744       0 gen_server:loop/6   
========================================================================================
      ]]></code>
  </section>

  <section>
    <title>Print to File</title>
    <p>At any time, the current Erlang Top display can be dumped to a
      text file with function 
      <seemfa marker="etop#dump/1"><c>etop:dump/1</c></seemfa>.
      </p>
  </section>

  <section>
    <title>Stop</title>
    <p>To stop Erlang Top, use function 
    <seemfa marker="etop#stop/0"><c>etop:stop/0</c></seemfa>.
    </p>
  </section>
</chapter>

