aboutsummaryrefslogtreecommitdiffstats
path: root/lib/percept/doc/src/percept_ug.xmlsrc
diff options
context:
space:
mode:
authorBjörn-Egil Dahlberg <[email protected]>2016-12-15 13:30:14 +0100
committerBjörn-Egil Dahlberg <[email protected]>2016-12-15 13:30:14 +0100
commit5794bc103abddca70e198857260390b896d737a7 (patch)
tree1f996d1c55e12b1282068d0914ab64c787de7c92 /lib/percept/doc/src/percept_ug.xmlsrc
parent6cc04a974724f0e115b2c8caa111418ecbd3db97 (diff)
downloadotp-5794bc103abddca70e198857260390b896d737a7.tar.gz
otp-5794bc103abddca70e198857260390b896d737a7.tar.bz2
otp-5794bc103abddca70e198857260390b896d737a7.zip
percept: Remove application
Diffstat (limited to 'lib/percept/doc/src/percept_ug.xmlsrc')
-rw-r--r--lib/percept/doc/src/percept_ug.xmlsrc223
1 files changed, 0 insertions, 223 deletions
diff --git a/lib/percept/doc/src/percept_ug.xmlsrc b/lib/percept/doc/src/percept_ug.xmlsrc
deleted file mode 100644
index 0d243cdabe..0000000000
--- a/lib/percept/doc/src/percept_ug.xmlsrc
+++ /dev/null
@@ -1,223 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
-
-<chapter>
- <header>
- <copyright>
- <year>2007</year>
- <year>2016</year>
- <holder>Ericsson AB, All Rights Reserved</holder>
- </copyright>
- <legalnotice>
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions 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>