2007 2016 Ericsson AB, All Rights Reserved 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. The Initial Developer of the Original Code is Ericsson AB. Percept Björn-Egil Dahlberg 2007-11-02 A percept_ug.xml

Percept, or Percept - Erlang Concurrency Profiling Tool, utilizes trace informations and profiler events to form a picture of the processes's and ports runnability.

Introduction

Percept uses erlang:trace/3 and erlang:system_profile/2 to monitor events from process states. Such states are,

waiting running runnable free exiting

There are some other states too, suspended, hibernating, and garbage collecting (gc). The only ignored state is gc and a process is considered to have its previous state through out the entire garbage collecting phase. The main reason for this, is that our model considers the gc as a third state neither active nor inactive.

A waiting or suspended process is considered an inactive process and a running or runnable process is considered an active process.

Events are collected and stored to a file. The file can be moved and analyzed on a different machine than the target machine.

Note, even if percept is not installed on your target machine, profiling can still be done via the module percept_profile located in runtime_tools.

Getting started
Profiling

There are a few ways to start the profiling of a specific code. The command percept:profile/3 is a preferred way.

The command takes a filename for the data destination file as first argument, a callback entry-point as second argument and a list of specific profiler options, for instance procs, as third argument.

Let's say we have a module called example that initializes our profiling-test and let it run under some defined manner designed by ourself. The module needs a start function, let's call it go and it takes zero arguments. The start arguments would look like:

percept:profile("test.dat", {test, go, []}, [procs]).

For a semi-real example we start a tree of processes that does sorting of random numbers. In our model below we use a controller process that distributes work to different client processes.

We can now start our test using percept:

Erlang (BEAM) emulator version 5.6 [async-threads:0] [kernel-poll:false]

Eshell V5.6  (abort with ^G)
1> percept:profile("test.dat", {sorter, go, [5, 2000, 15]}, [procs]).
Starting profiling.
ok

Percept sets up the trace and profiling facilities to listen for process specific events. It then stores these events to the test.dat file. The profiling will go on for the whole duration until sorter:go/3 returns and the profiling has concluded.

Data viewing

To analyze this file, use percept:analyze("test.dat"). We can do this on any machine with Percept installed. The command will parse the data file and insert all events in a RAM database, percept_db. The initial command will only prompt how many processes were involved in the profile. 

2> percept:analyze("test.dat").                                      
Parsing: "test.dat" 
Parsed 428 entries in 3.81310e-2 s.
    17 created processes.
    0 opened ports.
ok

To view the data we start the web-server using percept:start_webserver/1. The command will return the hostname and the a port where we should direct our favorite web browser. 

3> percept:start_webserver(8888).
{started,"durin",8888}
4>
Overview selection

Now we can view our data. The database has its content from percept:analyze/1 command and the webserver is started.

When we click on the overview button in the menu percept will generate a graph of the concurrency and send it to our web browser. In this view we get no details but rather the big picture. We can see if our processes behave in an inefficient manner. Dips in the graph represents low concurrency in the erlang system.

We can zoom in on different areas of the graph either using the mouse to select an area or by specifying min and max ranges in the edit boxes.

Measured time is presented in seconds if nothing else is stated.

 Overview selection
Processes selection

To get a more detailed description we can select the process view by clicking the processes button in the menu.

The table shows process id's that are click-able and direct you to the process information page, a lifetime bar that presents a rough estimate in green color about when the process was alive during profiling, an entry-point, its registered name if it had one and the process's parent id.

We can select which processes we want to compare and then hit the compare button on the top right of the screen.

Processes selection
Compare selection

The activity bar under the concurrency graph shows each process's runnability. The color green shows when a process is active (which is running or runnable) and the white color represents time when a process is inactive (waiting in a receive or is suspended).

To inspect a certain process click on the process id button, this will direct you to a process information page for that specific process.

Processes compare selection
Process information selection

Here we can some general information for the process. Parent and children processes, spawn and exit times, entry-point and start arguments.

We can also see the process' inactive times. How many times it has been waiting, statistical information and most importantly in which function.

The time percentages presented in process information are of time spent in waiting, not total run time.

Process information selection