aboutsummaryrefslogtreecommitdiffstats
path: root/lib/percept/doc/src/percept_ug.xmlsrc
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/percept/doc/src/percept_ug.xmlsrc
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/percept/doc/src/percept_ug.xmlsrc')
-rw-r--r--lib/percept/doc/src/percept_ug.xmlsrc222
1 files changed, 222 insertions, 0 deletions
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2007</year>
+ <year>2007</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+ </legalnotice>
+
+ <title>Percept</title>
+ <prepared>Bj�rn-Egil Dahlberg</prepared>
+ <docno></docno>
+ <date>2007-11-02</date>
+ <rev>A</rev>
+ <file>percept_ug.xml</file>
+ </header>
+ <p>
+ Percept, or Percept - Erlang Concurrency Profiling Tool, utilizes trace
+ informations and profiler events to form a picture of the processes's and
+ ports runnability.
+ </p>
+
+ <section>
+ <title>Introduction</title>
+ <p>
+ Percept uses <c>erlang:trace/3</c> and <c>erlang:system_profile/2</c> to monitor events from
+ process states. Such states are,</p>
+ <list>
+ <item>waiting</item>
+ <item>running</item>
+ <item>runnable</item>
+ <item>free</item>
+ <item>exiting</item>
+ </list>
+ <p>
+ There are some other states too, <c>suspended</c>, <c>hibernating</c>, and
+ garbage collecting (<c>gc</c>). The only ignored state is <c>gc</c> 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 <c>gc</c> as a third state neither active nor inactive.
+ </p>
+ <p>
+ A waiting or suspended process is considered an inactive process and a running or
+ runnable process is considered an active process.
+ </p>
+ <p>
+ Events are collected and stored to a file. The file can be moved and
+ analyzed on a different machine than the target machine.
+ </p>
+ <p>
+ Note, even if percept is not installed on your target machine, profiling
+ can still be done via the module <seealso marker="percept_profile">percept_profile</seealso>
+ located in runtime_tools.
+ </p>
+ </section>
+ <section>
+ <title>Getting started</title>
+ <section>
+ <title>Profiling</title>
+ <p>
+ There are a few ways to start the profiling of a specific code. The
+ command <c>percept:profile/3</c> is a preferred way.
+ </p>
+ <p>
+ 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 <c>procs</c>, as third
+ argument.
+ </p>
+ <p>
+ 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:
+ </p>
+ <p><c>percept:profile("test.dat", {test, go, []}, [procs]).</c></p>
+ <p>
+ 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.
+ </p>
+ <codeinclude file="sorter.erl" tag="" type="none"></codeinclude>
+ <p>We can now start our test using percept:</p>
+ <pre>
+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
+ </pre>
+ <p>
+ Percept sets up the trace and profiling facilities to listen for process
+ specific events. It then stores these events to the <c>test.dat</c>
+ file. The profiling will go on for the whole duration until
+ <c>sorter:go/3</c> returns and the profiling has concluded.
+ </p>
+ </section>
+ <section>
+ <title>Data viewing</title>
+ <p>
+ To analyze this file, use <c>percept:analyze("test.dat")</c>. 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, <c>percept_db</c>. The
+ initial command will only prompt how many processes were involved in the
+ profile.
+ </p>
+ <pre>
+2> percept:analyze("test.dat").
+Parsing: "test.dat"
+Parsed 428 entries in 3.81310e-2 s.
+ 17 created processes.
+ 0 opened ports.
+ok
+ </pre>
+ <p>
+ To view the data we start the web-server using
+ <c>percept:start_webserver/1</c>. The command will return the hostname
+ and the a port where we should direct our favorite web browser.
+ </p>
+ <pre>
+3> percept:start_webserver(8888).
+{started,"durin",8888}
+4>
+ </pre>
+ <section>
+ <title>Overview selection</title>
+ <p>
+ Now we can view our data. The database has its content from
+ <c>percept:analyze/1</c> command and the webserver is started.
+ </p>
+ <p>
+ When we click on the <c>overview</c> 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <note>
+ <p>Measured time is presented in seconds if nothing else is stated.</p>
+ </note>
+ <image file="percept_overview.gif">
+ <icaption>Overview selection</icaption>
+ </image>
+ </section>
+ <section>
+ <title>Processes selection</title>
+ <p>
+ To get a more detailed description we can select the process view by
+ clicking the <c>processes</c> button in the menu.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ We can select which processes we want to compare and then hit the
+ <c>compare</c> button on the top right of the screen.
+ </p>
+ <image file="percept_processes.gif">
+ <icaption>Processes selection</icaption>
+ </image>
+ </section>
+ <section>
+ <title>Compare selection</title>
+ <p>
+ 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).
+ </p>
+ <p>
+ To inspect a certain process click on the process id button, this will
+ direct you to a process information page for that specific process.
+ </p>
+ <image file="percept_compare.gif">
+ <icaption>Processes compare selection</icaption>
+ </image>
+ </section>
+ <section>
+ <title>Process information selection</title>
+ <p>
+ Here we can some general information for the process. Parent and
+ children processes, spawn and exit times, entry-point and start arguments.
+ </p>
+ <p>
+ We can also see the process' inactive times. How many times it has
+ been waiting, statistical information and most importantly in which
+ function.
+ </p>
+ <p>
+ The time percentages presented in process information are of time spent in waiting, not total run time.
+ </p>
+ <image file="percept_processinfo.gif">
+ <icaption>Process information selection</icaption>
+ </image>
+ </section>
+ </section>
+ </section>
+</chapter>