pan HOWTO

intro

pan was developed to solve this common problem; what resources (CPU time and memory consumption) does a set of actions (a test case) consume? the basic idea is that you start the measurement, perform the test case and stop the measurement. this will generate a set of data files containing a wealth of information, which can then be processed to present e.g. at the current stage the program is similar in functionality to the OTP applications dbg and eprof, and the unix application top, as well as some extras. it is designed to run with minimal impact (which is sometimes huge) in an embedded environment.

alas, it is not a product, so your mileage will vary.


basic

pan should be run from an erlang node (the host). the host must be able to attach itself to the target, but should be hidden (erl -hidden). when pan is started, it will load itself on the target(s), and start a tracing process. the target process will generate a data file containing information about the operating system and the erlang emulator, as well as about the erlang processes and the erlang tables. when the target process(es) are terminated the data files will be moved to the host.

the data files are stored in a file tree that uses the name of the test case, the name of the CP and the timestamp to generate unique names. they can be analyzed in different fashions.


data taking

pan:start/stop

pan:start(Tc,Nodes,Procs,Flags,MatchSpecs).

pan:stop()

see the reference for a detailed description of the parameters. briefly; Tc (test case) is a tag used to label the data files, Nodes is a list of target nodes to run on, Procs is a list of processes to trace on, Flags is a list of tracing flags and Matches is a list of match specifications (see erlang tracing documentation (R9) (R8) (R7)). (if the parameters are not given as lists they will be treated as lists of length 1).

Tc can be the special atom ip, which means that the tracing info will display on the host terminal instead of being sent to file.

for the casual user the Flags parameter is typically either the prof or perf aliases or, for the expert, a list of trace flags. the resulting files are typically analyzed with the functions pan:prof, pan:perf or pan:scan, respectively.


analysis

pan:perf

the pan:perf function provide information about;

pan:prof

pan:prof implements a profiler, i.e. a tool that shows cpu usage per function. in this example the data was taken using the command pan:start(tst,'axd301@cp1-19','',prof,{'_',local}) pan:prof/1 shows the cpu usage per process (similar to pan:perf).
> pan:prof("/tmp/pan/tst").                          
cb_eprof:28: end of trace
all; N = 29, 1127459 us 1127459 us/proc (100.0000)
  process tag                                                    procs    cpu%
  dpComServer.................................................     1.0    53.7
  plcMemory...................................................     1.0    17.1
  cpmServer...................................................     1.0    11.7
  sbm.........................................................     1.0     6.1
pan:prof/2 shows the cpu usage per function for a process (in this case plcMemory).
> pan:prof("/tmp/pan/tst",plcMemory).
plcMemory; N = 1, 192779 us 192779 us/proc (100.000)
  MFA                                                            calls    cpu%
  {ets,local_info,3}..........................................  2430.0    30.2
  {ets,db_info,2}.............................................  2430.0    27.6
  {plcMemory,do_calculate,6}..................................     1.0    24.6
  {ets,info,2}................................................  2430.0    14.7
  {ets,all,0}.................................................     1.0     1.7
  {ets,insert,2}..............................................    32.0     0.4
  {ets,lookup,2}..............................................    30.0     0.3
pan:prof/3 shows the cpu usage per function for a given process and stack.
> pan:prof("/tmp/pan/tst",plcMemory,[{plcMemory,check_loop,5},{timer,tc,3},{plcMemory,calculate,3},{plcMemory,do_calculate,6}]).
MFA                                                            calls       cpu%
{plcMemory,check_loop,5}.....................................      0       0.0%
{timer,tc,3}.................................................      1       0.0%
{plcMemory,calculate,3}......................................      1       0.0%
{plcMemory,do_calculate,6}...................................      1      24.6%
   , {ets,info,2}............................................   2430      72.6%
   , {ets,insert,2}..........................................     30       0.4%
   , {ets,lookup,2}..........................................     30       0.3%
   , {ets,delete,1}..........................................      1       0.1%
   , {ets,rename,2}..........................................      1       0.0%
   , {ets,new,2}.............................................      1       0.0%
total                                                                     98.0%
the special case where the stack is the empty atom '' finds the most expensive stack;
> pan:prof("/tmp/pan/tst",plcMemory,'').
MFA                                                            calls       cpu%
{plcMemory,check_loop,5}.....................................      0       0.0%
{timer,tc,3}.................................................      1       0.0%
{plcMemory,calculate,3}......................................      1       0.0%
{plcMemory,do_calculate,6}...................................      1      24.6%
{ets,info,2}.................................................   2430      14.7%
{ets,local_info,3}...........................................   2430      30.2%
{ets,db_info,2}..............................................   2430      27.6%
total                                                                     97.3%

pan:scan

scans the contents of a trace file, filters each trace message and (optionally) prints it.the filter can be either a (list of) term(s), in which case the trace message is printed if it contains the term(s), or a callback function. the callback function can do anything it wants with the messages.


debugging

pan:dbg

provides functionality similar to the OTP application dbg.
the reference

installation

available via anonymous cvs from www.sourceforge.net/projects/jungerl (cvsroot pserver:anonymous@cvs.sourceforge.net:/cvsroot/jungerl) or the sourceforge tarballs http://cvs.sourceforge.net/cvstarballs/jungerl-cvsroot.tar.gz
mats.cronqvist@ericsson.com
Last modified: Wed Mar 26 11:29:40 MET 2003