From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/percept/doc/src/percept_ug.xmlsrc | 222 ++++++++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 lib/percept/doc/src/percept_ug.xmlsrc (limited to 'lib/percept/doc/src/percept_ug.xmlsrc') diff --git a/lib/percept/doc/src/percept_ug.xmlsrc b/lib/percept/doc/src/percept_ug.xmlsrc new file mode 100644 index 0000000000..1164e26143 --- /dev/null +++ b/lib/percept/doc/src/percept_ug.xmlsrc @@ -0,0 +1,222 @@ + + + + +
+ + 2007 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights 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 + +
+
+
+ -- cgit v1.2.3