OTP-8058 The GUI parts are rewritten to use wxWidgets. Thanks Olle

          Mattsson!

          For the time being it is still possible to use the old GS based
          version of the tool, but it is deprecated. The wxWidgets based
          version is started by default.

          A new tutorial has been added to the documentation. It is based
          on Jayson Vantuyl's article
          http://souja.net/2009/04/making-sense-of-erlangs-event-tracer.htm
          l.

          The functions et:trace_me/4 and et:trace_me/5 has been introduced
          in order to replace the deprecated functions et:report_event/4
          and et:report_event/5. Hopefully the new names makes it a little
          more obvious what the intended usage of the functions are.

          A print function has been added to the GUI, in order to enable
          printing of sequence charts.

          More functionality for hiding unwanted events has been added to
          the GUI.

          The max_events, hide_unknown and display_mode configuration
          parameters to et_viewer is not used any more. Now the event cache
          in the Viewer only contains those events that actually are
          displayed in the GUI.

1 files changed, 273 insertions, 0 deletions

diff --git a/lib/et/doc/src/et_tutorial.xmlsrc b/lib/et/doc/src/et_tutorial.xmlsrc
new file mode 100644
index 0000000000..5c2a5a97e4
--- /dev/null
+++ b/lib/et/doc/src/et_tutorial.xmlsrc
@@ -0,0 +1,273 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2009</year><year>2009</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&aring;kan Mattsson</prepared>
+    <responsible>H&aring;kan Mattsson</responsible>
+    <docno></docno>
+    <approved>H&aring;kan Mattsson</approved>
+    <checked></checked>
+    <date></date>
+    <rev>%VSN%</rev>
+  </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. Avoid using 100.</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>