Percept Application
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
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,
Percept Application
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
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
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
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
Percept Application
11
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.
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
14
Percept Application
1.2: egd
Percept Application
15
16
Percept Application
1.2: egd
Percept Application
17
18
Percept Application
1.2: egd
Percept Application
19
Chapter 1: Percept Users Guide For more information regarding ESI, please see inets application [mod esi].
20
Percept Application
egd
The following functions are exported:
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
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:
ok |
ok, Port
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,
percept prole
The following functions are exported:
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
egd
egd
Erlang Module
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].
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
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()
Percept Application
25
percept
See also: percept prole [page 27]. stop webserver() ok | error, not started
Stops webserver.
26
Percept Application
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
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
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 Application
31
32
Percept Application