| .

Erlang SMP Profiling tool (ESP)
Author: Björn-Egil Dahlberg
Date: April 2007
Contact: egil@erix.ericsson.se
== INSTALLATION ==

The main package is compiled using the existing Makefile and make. Type

bash# make

The scripts builds esp.beam espdb.beam espdb_information.beam esp_analyzer.beam esp_httpd.beam esp_html.beam and the .beam files are placed in the ./ebin/ directory.

A few different options exists in the Makefile, "all" which is default and builds all packages except GD tool library. Options esp, html, database and gif are subpackages that are built with the default option.

The gd-library must be built separately. The interface and gd-driver, which is a modified version of gif-1.0, is located under tools/esp-gif/.

bash# cd tools/esp-gif/ bash# make bash# cd ../.. bash# cp tools/esp-gif/ebin/* ebin/.

Now all packages are built and located at their proper places.

== RUNNING ==

To run the ESP application it is required to use an erlang runtime system with erlang:system_profile() tracing feature.

To start the application either type

bash# make start

or invoke your erlang emulator directly. The ebin/ path is required. The esp_httpd:start() starts a inet http server on port 8888 on the machine running the emulator. Replace "erl" with the path and executable erlang emulator with system_profile feature.

bash# erl -pa ebin -s esp_httpd start

For data gathering only, the http server is not necessary.

bash# erl -pa ebin

== PROFILING ==

After starting the emulator with correct paths you are ready to commence concurrency profiling. The profiler does *NOT* need to be started with SMP support. It will determine potential concurrency in your application which is in direct relation with serialization issues or synchronization points.

Start by starting the profiler and supply a filename for output data.

> esp:profile("output.dat").

Then start the application (or module/group of processes) you want to analyze.

> application_example:start().

Let the application do something you are curious about and then terminate both the application and the profiler.

> application_example:stop(). > esp:stop().

== VIEWING AND ANALYZING CONCURRENCY ==

Make sure your file with profiling data is in the directory ./datafiles/. The web http server searches this path for possible data files.

The emulator does not need the profiling feature previously mentioned for this part. Any R11B (or older) emulator should suffice. Start your emulator with

bash# make start

or directly

bash# erl -pa ebin -s esp_httpd start

The command(s) starts a erlang emulator running a esp http server. Direct your favoite browser to http://localhost:8888

To fill the database with trace data either use,

> esp:analyze("datafiles/output.dat").

in the erlang shell where "datafiles/output.dat" is the location of your trace data file.

You may use the web interface for parsing also, see below.

The Web Interface.

1. The first page is just a welcoming page. *click* the "Analyzer" link to view parsable data files.

2. The database page lists all parsable trace data files located in directory ./datafiles/.

3. *click* on the file you want to examine.

4. The http server will now request esp to parse the file and restore all relevant data into the esp database. This step is equivalent to esp:analyze("datafiles/output.dat") previously mentioned. A "View" link will appear when then parsing is finished. *click* "View".

5. The overview page produces a graph of system concurrency over time. You may zoom any interval by clicking on the graph and selecting an intresting range to view more closely. When you have selected a suitable interval press the "Update" button. A new Overview page will appear with the desired interval.

6. Besides the overview a "Code location" link and a "Processes" link exists.

7. Code location shows a table of active versus inactive processes with MFA entry points and time in seconds when the event occured. The time is a representation of timestamps with starting time at first received event.

8. Processes lists all registered processes during the interval with Process ID, Start/ Stop /Life time, Process entry point (as Module, Function Arity), registered name and parent process ID. Select intresting processes and *click* the button "Compare".

9. The concurrency page shows a graph of system concurrency and a bar for each process. Green represents an active state, White an inactive state and grey when the process did not exist. No zooming exists here.

Remember, this is a prototype. There are several issues that needs to be adressed. If you find severe problems please send me and email (egil@erix.ericsson.se). Comments (positive or negative) or feature request are also welcomed. Several sections of the profiling tool is under revision but this is a working model. Due to time limitations not all features were included as original planned.