0% found this document useful (0 votes)
78 views36 pages

Percept Application

The document is a user guide for the Percept application, which is a tool for visualizing Erlang application concurrency and identifying bottlenecks. It discusses how to use Percept to profile an Erlang application by collecting trace events and storing them in a file. The file can then be analyzed to generate visualizations of process activity and concurrency over time. It also describes the egd module for rendering 2D images in Erlang, which Percept uses to generate graphs in its web interface.
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
78 views36 pages

Percept Application

The document is a user guide for the Percept application, which is a tool for visualizing Erlang application concurrency and identifying bottlenecks. It discusses how to use Percept to profile an Erlang application by collecting trace events and storing them in a file. The file can then be analyzed to generate visualizations of process activity and concurrency over time. It also describes the egd module for rendering 2D images in Erlang, which Percept uses to generate graphs in its web interface.
Copyright
© Attribution Non-Commercial (BY-NC)
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 36

Percept Application

version 0.7

A Typeset in L TEX from SGML source using the DocBuilder-0.9.8.4 Document System.

Contents
1 Percept Users Guide 1.1 Percept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 egd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 File example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3 ESI example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Percept Reference Manual 2.1 2.2 2.3 egd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . percept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . percept prole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 1 2 12 12 12 18 21 23 25 27

List of Figures

29

Percept Application

iii

iv

Percept Application

Chapter 1

Percept Users Guide


Percept is an akronym for Percept - er lang concurrency proling tool. It is a tool to visualize application level concurrency and indentify concurrency bottlenecks.

1.1

Percept

Percept, or Percept - Erlang Concurrency Proling Tool, utilizes trace informations and proler events to form a picture of the processess and ports runnability.

1.1.1 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 le. The le can be moved and analyzed on a different machine than the target machine. Note, even if percept is not installed on your target machine, proling can still be done via the module percept prole [page 27] located in runtime tools.

Percept Application

Chapter 1: Percept Users Guide

1.1.2 Getting started


Proling There are a few ways to start the proling of a specic code. The command percept:profile/3 is a preferred way. The command takes a lename for the data destination le as rst argument, a callback entry-point as second argument and a list of specic proler options, for instance procs, as third argument. Lets say we have a module called example that initializes our proling-test and let it run under some dened manner designed by ourself. The module needs a start function, lets 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. -module(sorter). -export([go/3,loop/0,main/4]). go(I,N,M) -> spawn(?MODULE, main, [I,N,M,self()]), receive done -> ok end. main(I,N,M,Parent) -> Pids = lists:foldl( fun(_,Ps) -> [ spawn(?MODULE,loop, []) | Ps] end, [], lists:seq(1,M)), lists:foreach( fun(_) -> send_work(N,Pids), gather(Pids) end, lists:seq(1,I)), lists:foreach( fun(Pid) -> Pid ! {self(), quit} end, Pids), gather(Pids), Parent ! done. send_work(_,[]) -> ok; send_work(N,[Pid|Pids]) -> Pid ! {self(),sort,N}, send_work(round(N*1.2),Pids). loop() -> receive {Pid, sort, N} -> dummy_sort(N),Pid ! {self(), done},loop(); {Pid, quit} -> Pid ! {self(), done} end.

Percept Application

1.1: Percept dummy_sort(N) -> lists:sort([ random:uniform(N) || _ <- lists:seq(1,N)]). gather([]) -> ok; gather([Pid|Pids]) -> receive {Pid, done} -> gather(Pids) end. 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 proling facilities to listen for process specic events. It then stores these events to the test.dat le. The proling will go on for the whole duration until sorter:go/3 returns and the proling has concluded. Data viewing To analyze this le, use percept:analyze("test.dat"). We can do this on any machine with Percept installed. The command will parse the data le and insert all events in a RAM database, percept db. The initial command will only prompt how many processes were involved in the prole. 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

Percept Application

Chapter 1: Percept Users Guide 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 inefcient 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.

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

Percept Application

1.1: Percept

Figure 1.1: Overview selection

Percept Application

Chapter 1: Percept Users Guide 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 ids 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 proling, an entry-point, its registered name if it had one and the processs parent id. We can select which processes we want to compare and then hit the compare button on the top right of the screen.

Percept Application

1.1: Percept

Figure 1.2: Processes selection

Percept Application

Chapter 1: Percept Users Guide Compare selection The activity bar under the concurrency graph shows each processs 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 specic process.

Percept Application

1.1: Percept

Figure 1.3: Processes compare selection

Percept Application

Chapter 1: Percept Users Guide 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.

10

Percept Application

1.1: Percept

Figure 1.4: Process information selection

Percept Application

11

Chapter 1: Percept Users Guide

1.2

egd

1.2.1 Introduction
The egd module is an interface for 2d-image rendering and is used by Percept to generate dynamic graphs to its web pages. All code is pure erlang, no drivers needed. The library is intended for small to medium image sizes with low complexity for optimal performance. The library handles horizontal lines better then vertical lines. The foremost purpose for this module is to enable users to generate images from erlang code and/or datasets and to send these images to either les or web servers.

1.2.2 File example


Drawing examples: -module(img). -export([do/0]). do() -> Im = egd:create(200,200), Red = egd:color({255,0,0}), Green = egd:color({0,255,0}), Blue = egd:color({0,0,255}), Black = egd:color({0,0,0}), Yellow = egd:color({255,255,0}), % Line and fillRectangle egd:filledRectangle(Im, {20,20}, {180,180}, Red), egd:line(Im, {0,0}, {200,200}, Black), egd:save(egd:render(Im, png), "/home/egil/test1.png"), egd:filledEllipse(Im, {45, 60}, {55, 70}, Yellow), egd:filledEllipse(Im, {145, 60}, {155, 70}, Blue), egd:save(egd:render(Im, png), "/home/egil/test2.png"), R = 80, X0 = 99, Y0 = 99, X0 + trunc(R*math:cos(A*math:pi()*2/360)), Y0 + trunc(R*math:sin(A*math:pi()*2/360)) } || A <- lists:seq(0,359,5)], lists:map( fun({X,Y}) -> egd:rectangle(Im, {X-5, Y-5}, {X+5,Y+5}, Green) end, Pts), Pts = [ {

12

Percept Application

1.2: egd egd:save(egd:render(Im, png), "/home/egil/test3.png"), % Text Filename = filename:join([code:priv_dir(percept), "fonts", "6x11_latin1.wingsfont"]), Font = egd_font:load(Filename), {W,H} = egd_font:size(Font), String = "egd says hello", Length = length(String), egd:text(Im, {round(100 - W*Length/2), 200 - H - 5}, Font, String, Black), egd:save(egd:render(Im, png), "/home/egil/test4.png"), egd:destroy(Im).

Percept Application

13

Chapter 1: Percept Users Guide

Figure 1.5: test1.gif

14

Percept Application

1.2: egd

Figure 1.6: test2.gif

Percept Application

15

Chapter 1: Percept Users Guide

Figure 1.7: test3.gif

16

Percept Application

1.2: egd

Figure 1.8: test4.gif

Percept Application

17

Chapter 1: Percept Users Guide

1.2.3 ESI example


Using egd with inets ESI to generate images on the y: -module(img_esi). -export([image/3]). image(SessionID, _Env, _Input) -> mod_esi:deliver(SessionID, header()), Binary = my_image(), mod_esi:deliver(SessionID, binary_to_list(Binary)). my_image() -> Im = egd:create(300,20), Black = egd:color({0,0,0}), Red = egd:color({255,0,0}), egd:filledRectangle(Im, {30,14}, {270,19}, Red), egd:rectangle(Im, {30,14}, {270,19}, Black), Filename = filename:join([code:priv_dir(percept), "fonts", "6x11_latin1.wingsfont"]), Font = egd_font:load(Filename), egd:text(Im, {30, 0}, Font, "egd with esi callback", Black), Bin = egd:render(Im, png), egd:destroy(Im), Bin. header() -> "Content-Type: image/png\r \r ".

18

Percept Application

1.2: egd

Figure 1.9: Example of result.

Percept Application

19

Chapter 1: Percept Users Guide For more information regarding ESI, please see inets application [mod esi].

20

Percept Application

Percept Reference Manual


Short Summaries
Erlang Module egd [page 23] egd - erlang graphical drawer. Erlang Module percept [page 25] Percept - Erlang Concurrency Proling Tool. Erlang Module percept prole [page 27] Percept Collector.

egd
The following functions are exported:

color(Color:: byte(), byte(), byte() ) [page 23] Creates a color reference.

color()

create(Width::integer(), Height::integer()) - egd image() [page 23] Creates an image area and returns its reference. destroy(Image::egd image()) [page 23] Destroys the image.
ok

filledEllipse(Image::egd image(), P1::point(), P2::point(), Color::color()) - ok [page 23] Creates a lled ellipse object. filledRectangle(Image::egd image(), P1::point(), P2::point(), Color::color()) - ok [page 23] Creates a lled rectangle object. line(Image::egd image(), P1::point(), P2::point, Color::color()) ok [page 23] Creates a line object from P1 to P2 in the image. rectangle(Image::egd image(), P1::point(), P2::point(), Color::color()) - ok [page 23] Creates a rectangle object. render(Image::egd image()) - binary() [page 23] Equivalent to render(Image, png, [ render engine, opaque ]). render(Image::egd image(), Type::png | raw bitmap) - binary() [page 23] Equivalent to render(Image, Type, [ render engine, opaque ]). render(Image::egd image(), Type::png | raw bitmap, Options::[render option()]) - binary() [page 23] Renders a binary from the primitives specied by egd image(). save(Binary::binary(), Filename::string()) [page 24] Saves the binary to le.
ok

Percept Application

21

Percept Reference Manual

text(Image::egd image(), P::point(), Font::font(), Text::string(), Color::color()) - ok [page 24] Creates a text object.

percept
The following functions are exported:

analyze(Filename::string()) [page 25] Analyze le. profile(Filename::string()) [page 25]

ok |

error, Reason | already started, Port ok,

ok, Port

profile(Filename::string(), Options::[percept option()]) Port | already started, Port [page 25]

profile(Filename::string(), MFA::mfa(), Options::[percept option()]) - ok | already started, Port | error, not started [page 25] start webserver() started, Hostname, Port | [page 25] Starts webserver. start webserver(Port::integer()) AssignedPort | error, Reason [page 25] Starts webserver. stop profile() [page 26]
ok | error, Reason

started, Hostname,

error, not started error, not started

stop webserver() - ok | [page 26] Stops webserver.

percept prole
The following functions are exported:

start(Filename::string()) ok, Port | [page 27] Equivalent to start(Filename, [procs]).

already started, Port ok, Port

start(Filename::string(), Options::[percept option()]) | already started, Port [page 27] Starts proling with supplied options.

start(Filename::string(), MFA::mfa(), Options::[percept option()]) - ok | already started, Port | error, not started [page 27] Starts proling at the entrypoint specied by the MFA. stop() - ok | error, not started [page 27] Stops proling.

22

Percept Application

Percept Reference Manual

egd

egd
Erlang Module

egd - erlang graphical drawer

DATA TYPES
color() egd image() point() = integer(), integer() render engine, opaque | render engine, alpha render option() =

Exports
color(Color:: byte(), byte(), byte() ) Creates a color reference. create(Width::integer(), Height::integer()) egd image() color()

Creates an image area and returns its reference. destroy(Image::egd image()) Destroys the image. filledEllipse(Image::egd image(), P1::point(), P2::point(), Color::color()) Creates a lled ellipse object. filledRectangle(Image::egd image(), P1::point(), P2::point(), Color::color()) Creates a lled rectangle object. line(Image::egd image(), P1::point(), P2::point, Color::color()) Creates a line object from P1 to P2 in the image. rectangle(Image::egd image(), P1::point(), P2::point(), Color::color()) Creates a rectangle object. render(Image::egd image()) binary() ok ok ok ok ok

Percept Application

23

egd

Percept Reference Manual Equivalent to render(Image, png, [ render engine, opaque ]) [page 24].

render(Image::egd image(), Type::png | raw bitmap) -

binary()

Equivalent to render(Image, Type, [ render engine, opaque ]) [page 24]. render(Image::egd image(), Type::png | raw bitmap, Options::[render option()]) binary() Renders a binary from the primitives specied by egd image(). The binary can either be a raw bitmap with rgb tripplets or a binary in png format. save(Binary::binary(), Filename::string()) Saves the binary to le. text(Image::egd image(), P::point(), Font::font(), Text::string(), Color::color()) ok Creates a text object. ok

24

Percept Application

Percept Reference Manual

percept

percept
Erlang Module

Percept - Erlang Concurrency Proling Tool This module provides the user interface for the application.

DATA TYPES
percept option() = procs | ports | exclusive

Exports
analyze(Filename::string()) Analyze le. profile(Filename::string()) ok, Port | already started, Port ok | error, Reason

See also: percept prole [page 27]. profile(Filename::string(), Options::[percept option()]) already started, Port See also: percept prole [page 27]. profile(Filename::string(), MFA::mfa(), Options::[percept option()]) already started, Port | error, not started See also: percept prole [page 27]. start webserver() Types: started, Hostname, Port | error, Reason ok | ok, Port |

Hostname = string() Port = integer() Reason = term()


Starts webserver. start webserver(Port::integer()) Reason Types: started, Hostname, AssignedPort | error,

Hostname = string()

Percept Application

25

percept

Percept Reference Manual

AssignedPort = integer() Reason = term()


Starts webserver. If port number is 0, an available port number will be assigned by inets. stop profile() ok | error, not started

See also: percept prole [page 27]. stop webserver() ok | error, not started

Stops webserver.

26

Percept Application

Percept Reference Manual

percept prole

percept prole
Erlang Module

Percept Collector This module provides the user interface for the percept data collection (proling).

DATA TYPES
percept option() = procs | ports | exclusive

Exports
start(Filename::string()) ok, Port | already started, Port

Equivalent to start(Filename, [procs]) [page 27]. start(Filename::string(), Options::[percept option()]) already started, Port Types: ok, Port |

Port = port()
Starts proling with supplied options. All events are stored in the le given by Filename. An explicit call to stop/0 is needed to stop proling. start(Filename::string(), MFA::mfa(), Options::[percept option()]) already started, Port | error, not started Types: ok |

Port = port()
Starts proling at the entrypoint specied by the MFA. All events are collected, this means that processes outside the scope of the entry-point are also proled. No explicit call to stop/0 is needed, the proling stops when the entry function returns. stop() ok | error, not started

Stops proling.

Percept Application

27

percept prole

Percept Reference Manual

28

Percept Application

List of Figures
1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 Overview selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processes selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processes compare selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process information selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . test1.gif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . test2.gif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . test3.gif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . test4.gif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 7 9 11 14 15 16 17 19

Percept Application

29

List of Figures

30

Percept Application

Index of Modules and Functions


Modules are typed in this way . Functions are typed in this way. analyze/1 percept , 25 color/1 egd , 23 create/1 egd , 23 destroy/1 egd , 23

percept prole start/1, 27 stop/0, 27


profile/1 percept , 25 rectangle/1 egd , 23 render/1 egd , 23, 24 save/1 egd , 24 start/1 percept prole , 27 start_webserver/0 percept , 25 start_webserver/1 percept , 25 stop/0 percept prole , 27 stop_profile/0 percept , 26 stop_webserver/0 percept , 26 text/1 egd , 24

egd
color/1, 23 create/1, 23 destroy/1, 23 filledEllipse/1, 23 filledRectangle/1, 23 line/1, 23 rectangle/1, 23 render/1, 23, 24 save/1, 24 text/1, 24 filledEllipse/1 egd , 23 filledRectangle/1 egd , 23 line/1 egd , 23

percept analyze/1, 25 profile/1, 25 start_webserver/0, 25 start_webserver/1, 25 stop_profile/0, 26 stop_webserver/0, 26

Percept Application

31

Index of Modules and Functions

32

Percept Application

You might also like