The R13B03 release.OTP_R13B03

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>