<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2009</year><year>2011</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.
</legalnotice>
<title>Tutorial</title>
<prepared>Håkan Mattsson</prepared>
<responsible>Håkan Mattsson</responsible>
<docno></docno>
<approved>Håkan Mattsson</approved>
<checked></checked>
<date></date>
<rev>%VSN%</rev>
<file>et_tutorial.xml</file>
</header>
<section>
<title>Visualizing Message Sequence Charts</title>
<p>The easiest way of using <c>ET</c>, is to just use it as a
graphical tool for displaying message sequence charts. In order to
do that you need to first start a <c>Viewer</c> (which by default
starts a <c>Collector</c>):</p>
<code type="none"><![CDATA[
{ok, ViewerPid} = et_viewer:start([{title,"Coffee Order"}]),
CollectorPid = et_viewer:get_collector_pid(ViewerPid).]]></code>
<marker id="report_event"></marker>
<p>Then you send events to the <c>Collector</c>
with the function <c>et_collector:report_event/6</c> like this:</p>
<code type="none"><![CDATA[
et_collector:report_event(CollectorPid,85,from,to,message,extra_stuff).]]></code>
<p>The <c>Viewer</c> will automatically pull events from the
<c>Collector</c> and display them on the screen.</p>
<p>The number (in this case 85) is an integer from 1 to 100 that
specifies the "detail level" of the message. The higher the
number, the more important it is. This provides a crude form of
priority filtering.</p>
<p>The <c>from</c>, <c>to</c>, and <c>message</c> parameters are
exactly what they sound like. <c>from</c> and <c>to</c> are
visualized in the <c>Viewer</c> as "lifelines", with the message
passing from one to the other. If <c>from</c> and <c>to</c> are
the same value, then it is displayed next to the lifeline as an
"action". The <c>extra_stuff </c>value is simply data that you can
attach that will be displayed when someone actually clicks on the
action or message in the <c>Viewer</c> window.</p>
<p>The module <c>et/examples/et_display_demo.erl</c> illustrates
how it can be used:</p>
<codeinclude file="../../examples/et_display_demo.erl" tag="%module" type="erl"></codeinclude>
<p>When you run the <c>et_display_demo:test().</c> function in the
example above, the <c>Viewer</c> window will look like this:</p>.
<p></p>
<image file="coffee_order.png">
<icaption>Screenshot of the <c>Viewer</c> window</icaption>
</image>
</section>
<section>
<title>Four Modules</title>
<p>The event tracer framework is made up of four modules:</p>
<list type="bulleted">
<item><p><c>et</c></p></item>
<item><p><c>et_collector</c></p></item>
<item><p><c>et_viewer</c></p></item>
<item><p><c>et_selector</c></p></item>
</list>
<p>In addition, you'll probably want to familiarize yourself with
the <c>dbg</c> module and possibly <c>seq_trace</c> module as
well.</p>
</section>
<section>
<title>The Event Tracer Interface</title>
<p>The <c>et</c> module is not like other modules. It contains a
function called <c>et:trace_me/5</c>. Which is a function that
does not do any useful stuff at all. Its sole purpose is to be a
function that is easy to trace. A call to it may be something
like:</p>
<code type="none"><![CDATA[
et:trace_me(85,from,to,message,extra_stuff).]]></code>
<p>The parameters to <c>et:trace_me/5</c> are the same as to
<seealso
marker="#report_event"><c>et_collector:report_event/6</c></seealso>
in the previous chapter. The big difference between the two is in
the semantics of the two functions. The second actually reports an
<c>Event</c> to the <c>Collector</c> while the first does nothing,
it just returns the atom <c>hopefully_traced</c>. In order to make
the parameters to <c>et:trace_me/5</c> turn up in the
<c>Collector</c>, tracing of that function must be activated and
the <c>Collector</c> must be registered as a <c>Tracer</c> of the
<c>Raw Trace Data</c>.</p>
<p>Erlang tracing is a seething pile of pain that involves
reasonably complex knowledge of clever ports, tracing return
formats, and specialized tracing <c>MatchSpecs</c> (which are
really their own special kind of hell). The tracing mechanism is
very powerful indeed, but it can be hard to grasp.</p>
<p>Luckily there is a simplified way to start tracing of
<c>et:trace_me/5</c> function calls. The idea is that you should
instrument your code with calls to <c>et:trace_me/5</c> in
strategic places where you have interesting information available
in your program. Then you just start the <c>Collector</c> with
global tracing enabled:</p>
<code type="none"><![CDATA[
et_viewer:start([{trace_global, true}, {trace_pattern, {et,max}}]).]]></code>
<p>This will start a <c>Collector</c>, a <c>Viewer</c> and also
start the tracing of <c>et:trace_me/5</c> function calls. The
<c>Raw Trace Data</c> is collected by the <c>Collector</c> and a
view of it is displayed on the screen by the <c>Viewer</c>. You
can define your own "views" of the data by implementing your own
<c>Filter</c> functions and register them in the
<c>Viewer</c>.</p>
</section>
<section>
<title>The Collector and Viewer</title>
<p>These two pieces work in concert. Basically, the
<c>Collector</c> receives <c>Raw Trace Data</c> and processes it
into <c>Events</c> in a <c>et</c> specific format (defined in
<c>et/include/et.hrl</c>). The <c>Viewer</c> interrogates the
<c>Collector</c> and displays an interactive representation of the
data.</p>
<p>You might wonder why these aren't just one module. The
<c>Collector</c> is a generic full-fledged framework that allows
processes to "subscribe" to the <c>Events</c> that it
collects. One <c>Collector</c> can serve several
<c>Viewers</c>. The typical case is that you have one
<c>Viewer</c> that visualizes <c>Events</c> in one flavor and
another <c>Viewer</c> that visualizes them in another flavor. If
you for example are tracing a text based protocol like <c>HTML</c>
(or <c>Megaco/H.248</c>) it would be useful to be able to display
the <c>Events</c> as plain text as well as the internal
representation of the message. The architecture does also allow
you to implement your own <c>Viewer</c> program as long as it
complies to the protocol between the <c>Collector/Viewer</c>
protocol. Currently two kinds of <c>Viewers</c> exists. That is
the old <c>GS</c> based one and the new based on
<c>wxWidgets</c>. But if you feel for it you may implement your
own <c>Viewer</c>, which for example could display the
<c>Events</c> as ASCII art or whatever you feel useful.</p>
<p>The <c>Viewer</c> will by default create a <c>Collector</c> for
you. With a few options and some configuration settings you can
start collecting <c>Events</c>.</p>
<p>The <c>Collector</c> API does also allow you to save the
collected <c>Events</c> to file and later load them in a later
session.</p>
</section>
<section>
<title>The Selector</title>
<p>This is perhaps the most central module in the entirety of the
<c>et</c> suite. The <c>Collector</c> needs "filters" to convert
the <c>Raw Trace Data</c> into "events" that it can display. The
<c>et_selector</c> module provides the default <c>Filter</c> and
some API calls to manage the <c>Trace Pattern</c>. The
<c>Selector</c> provides various functions that achieve the
following:</p>
<list type="bulleted">
<item><p>Convert <c>Raw Trace Data</c> into an appropriate
<c>Event</c></p></item>
<item><p>Magically notice traces of the <c>et:trace_me/5</c>
function and make appropriate <c>Events</c></p></item>
<item><p>Carefully prevent translating the <c>Raw Trace Data</c>
twice</p></item>
<item><p>Manage a <c>Trace Pattern</c></p></item>
</list>
<p>The <c>Trace Pattern</c> is basically a tuple of a
<c>module</c> and a <c>detail level</c> (either an integer or the
atom max for full detail). In most cases the <c>Trace Pattern</c>
<c>{et,max}</c> does suffice. But if you do not want any runtime
dependency of <c>et</c> you can implement your own
<c>trace_me/5</c> function in some module and refer to that module
in the <c>Trace Pattern</c>.</p>
<p>The specified module flows from your instantiation of the
<c>Viewer</c>, to the <c>Collector</c> that it automatically
creates, gets stashed in as the <c>Trace Pattern</c>, and
eventually goes down into the bowels of the <c>Selector</c>.</p>
<p>The module that you specify gets passed down (eventually) into
<c>Selector</c>'s default <c>Filter</c>. The format of the
<c>et:trace_me/5</c> function call is hardcoded in that
<c>Filter</c>.</p>
</section>
<section>
<title>How To Put It Together</title>
<p>The <c>Collector</c> automatically registers itself to listen
for trace <c>Events</c>, so all you have to do is enable them.</p>
<p>For those people who want to do general tracing, consult the
<c>dbg</c> module on how to trace whatever you're interested in
and let it work its magic. If you just want <c>et:trace_me/5</c>
to work, do the following:</p>
<list type="ordered">
<item><p>Create a <c>Collector</c></p></item>
<item><p>Create a <c>Viewer</c> (this can do step #1 for you)</p></item>
<item><p>Turn on and pare down debugging</p></item>
</list>
<p>The module <c>et/examples/et_trace_demo.erl</c> achieves this.</p>
<codeinclude file="../../examples/et_trace_demo.erl" tag="%module" type="erl"></codeinclude>
<p>Running through the above, the most important points are:</p>
<list type="bulleted">
<item><p>Turn on global tracing</p></item>
<item><p>Set a <c>Trace Pattern</c></p></item>
<item><p>Tell <c>dbg</c> to trace function Calls</p></item>
<item><p>Tell it specifically to trace the <c>et:trace_me/5</c> function</p></item>
</list>
<p>When you run the <c>et_trace_demo:test()</c> function above, the
<c>Viewer</c> window will look like this screenshot:</p>.
<p></p>
<image file="coffee_order.png">
<icaption>Screenshot of the <c>Viewer</c> window</icaption>
</image>
</section>
</chapter>
