aboutsummaryrefslogtreecommitdiffstats
path: root/lib/et/doc/src/et_architecture.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/et/doc/src/et_architecture.xml')
-rw-r--r--lib/et/doc/src/et_architecture.xml554
1 files changed, 554 insertions, 0 deletions
diff --git a/lib/et/doc/src/et_architecture.xml b/lib/et/doc/src/et_architecture.xml
new file mode 100644
index 0000000000..44e262db96
--- /dev/null
+++ b/lib/et/doc/src/et_architecture.xml
@@ -0,0 +1,554 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2002</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>Usage</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>
+ <file>et_architecture.xml</file>
+ </header>
+
+ <section>
+ <title>Overview</title>
+ <p>The two major components of the Event Tracer (ET)
+ tool is a graphical sequence chart viewer (<c>et_viewer</c>)
+ and its backing storage (<c>et_collector</c>). One collector
+ may be used as backing storage for several simultaneous
+ viewers where each one may display a different view of
+ the same trace data.</p>
+ <p>The interface between the collector and its viewers
+ is public in order to enable other types of viewers.
+ However in the following text we will focus on usage
+ of the <c>et_viewer</c>.</p>
+ <p>The main start function is <c>et_viewer:start/1</c>.
+ It will by default start both an <c>et_collector</c> and
+ an <c>et_viewer</c>:</p>
+ <p></p>
+ <code type="none"><![CDATA[
+ % erl -pa et/examples
+ Erlang (BEAM) emulator version 2002.10.08 [source]
+
+ Eshell V2002.10.08 (abort with ^G)
+ 1> {ok, Viewer} = et_viewer:start([]).
+ {ok,<0.31.0>}
+ ]]></code>
+ <p>A viewer gets trace events from its collector
+ by polling it regularly for more events to display.
+ Trace events are for example reported to the collector with
+ <c>et_collector:report_event/6</c>:</p>
+ <code type="none"><![CDATA[
+ 2> Collector = et_viewer:get_collector_pid(Viewer).
+ <0.30.0>
+ 3> et_collector:report_event(Collector, 60, my_shell, mnesia_tm, start_outer,
+ "Start outer transaction"),
+ 3> et_collector:report_event(Collector, 40, mnesia_tm, my_shell, new_tid,
+ "New transaction id is 4711"),
+ 3> et_collector:report_event(Collector, 20, my_shell, mnesia_locker, try_write_lock,
+ "Acquire write lock for {my_tab, key}"),
+ 3> et_collector:report_event(Collector, 10, mnesia_locker, my_shell, granted,
+ "You got the write lock for {my_tab, key}"),
+ 3> et_collector:report_event(Collector, 60, my_shell, do_commit,
+ "Perform transaction commit"),
+ 3> et_collector:report_event(Collector, 40, my_shell, mnesia_locker, release_tid,
+ "Release all locks for transaction 4711"),
+ 3> et_collector:report_event(Collector, 60, my_shell, mnesia_tm, delete_transaction,
+ "End of outer transaction"),
+ 3> et_collector:report_event(Collector, 20, my_shell, end_outer,
+ "Transaction returned {atomic, ok}").
+ {ok,{table_handle,<0.30.0>,11,trace_ts,#Fun<et_collector.0.83904657>}}
+ 4>
+ ]]></code>
+ <p>This is a simulation of the process events caused by a Mnesia
+ transaction that writes a record in a local table:</p>
+ <code type="none">
+ mnesia:transaction(fun() -> mnesia:write({my_tab, key, val}) end).
+ </code>
+ <p>At this stage when we have a couple of events, it is time to
+ show how it looks like in the graphical interface of
+ <c>et_viewer</c>:</p>
+ <p></p>
+ <image file="sim_trans.gif">
+ <icaption>A simulated Mnesia transaction which writes one record</icaption>
+ </image>
+ <p>In the sequence chart, the actors (which symbolically has performed the
+ traced event) are shown as named vertical bars. The order of the
+ actors may be altered by dragging (hold mouse button 1 pressed during
+ the operation) the name tag of an actor and drop it elsewhere:</p>
+ <image file="sim_trans_move_actor.gif">
+ <icaption>Two actors has switched places</icaption>
+ </image>
+ <p>An event may be an action performed by one single actor (blue
+ text label) or it may involve two actors and is then depicted as an
+ arrow directed from one actor to another (red text label). Details of
+ an event can be shown by clicking (press and release the mouse button 1)
+ on the event label text or on the arrow:</p>
+ <p></p>
+ <image file="sim_trans_write_lock.gif">
+ <icaption>Details of a write lock message</icaption>
+ </image>
+ </section>
+
+ <section>
+ <title>Filters and dictionary</title>
+ <p>The Event Tracer (ET) uses named filters in various
+ contexts. An Event Trace filter is an <c>Erlang fun</c>
+ that takes some trace data as input and returns a possibly
+ modified version of it:
+ </p>
+ <p></p>
+ <code type="none">
+ filter(TraceData) -> true | {true, NewEvent} | false
+
+ TraceData = NewEvent | term()
+ NewEvent = record(event)
+ </code>
+ <p>The interface of the filter function is the same as the the
+ filter functions for the good old <c>lists:zf/2</c>. If the filter
+ returns <c>false</c> it means that the <c>TraceData</c> should be
+ dropped. <c>{true, NewEvent}</c> means that the <c>TraceData</c>
+ should be replaced with <c>NewEvent</c>. And <c>true</c> means that the
+ <c>TraceData</c> data already is an event record and that it
+ should be kept as it is.
+ </p>
+ <p>The first filter that the trace data is exposed for is
+ the collector filter. When a trace event is reported with
+ <c>et_collector:report/2</c> (or <c>et_collector:report_event/5,6</c>)
+ the first thing that
+ happens, is that a message is sent to the collector process
+ to fetch a handle that contains some useful stuff, such as
+ the collector filter fun and an ets table identifier.
+ Then the collector filter fun is applied and if it returns
+ <c>true</c> (or <c>{true, NewEvent}</c>), the event will
+ be stored in an ets table. As an optimization, subsequent
+ calls to <c>et_collector:report</c>-functions can use the handle
+ directly instead of the collector pid.
+ </p>
+ <p>The collector filter (that is the filter named
+ <c>collector</c>) is a little bit special, as its input
+ may be any Erlang term and is not limited to take an event
+ record as the other filter functions.
+ </p>
+ <p>The collector manages a key/value based dictionary, where
+ the filters are stored. Updates of the dictionary is
+ propagated to all subscribing processes. When a viewer is
+ started it is registered as a subscriber of dictionary updates.
+ </p>
+ <p>In a viewer there is only one filter that is active
+ and all trace events that the viewer gets from the
+ collector will pass thru that filter. By writing clever
+ filters it is possible to customize how the events
+ looks like in the viewer. The following filter replaces
+ the actor names <c>mnesia_tm</c> and <c>mnesia_locker</c>
+ and leaves everything else in the record as it was:
+ </p>
+ <p></p>
+ <codeinclude file="../../examples/et_demo.erl" tag="%mgr_actors" type="erl"></codeinclude>
+ <p>If we now add the filter to the running collector:
+ </p>
+ <p></p>
+ <code type="none"><![CDATA[
+ 4> Fun = fun(E) -> et_demo:mgr_actors(E) end.
+ #Fun<erl_eval.5.123085357>
+ 5> et_collector:dict_insert(Collector, {filter, mgr_actors}, Fun).
+ ok
+ 6>
+ ]]></code>
+ <p>you will see that the <c>Filter</c> menu in all viewers have
+ got a new entry called <c>mgr_actors</c>. Select it, and a new
+ viewer window will pop up:</p>
+ <p></p>
+ <image file="sim_trans_mgr_actors.gif">
+ <icaption>The same trace data in a different view</icaption>
+ </image>
+ <p>In order to see the nitty gritty details of an event
+ you may click on the event in order to start a contents
+ viewer for that event. In the contents viewer there is
+ also a filter menu in order to enable inspection of the
+ event from other views than the one selected in the viewer.
+ A click on the <c>new_tid</c> event will cause a contents
+ viewer window to pop up, showing the event in the
+ <c>mgr_actors</c> view:</p>
+ <p></p>
+ <image file="sim_trans_contents_viewer_mgr_actors.gif">
+ <icaption>The trace event in the mgr_actors view</icaption>
+ </image>
+ <p>Select the <c>collector</c> entry in the <c>Filters</c>
+ menu and a new contents viewer window will pop up
+ showing the same trace event in the collectors view:</p>
+ <p></p>
+ <image file="sim_trans_contents_viewer_collector.gif">
+ <icaption>The same trace event in the collectors view</icaption>
+ </image>
+ </section>
+
+ <section>
+ <title>Trace clients</title>
+ <p>As you have seen it is possible to use the
+ <c>et_collector:report</c>-functions explicitly. By using those functions
+ you can write your own trace client that reads trace data from any
+ source stored in any format and just feed the collector with it. You
+ may replace the default collector filter with a filter that converts
+ new exciting trace data formats to event-records or you may convert it
+ to an event-record before you invoke <c>et_collector:report/2</c> and
+ then rely on the default collector filter to handle the new
+ format.</p>
+ <p>There are also existing functions in the API that reads from
+ various sources and calls <c>et_collector:report/2</c>:</p>
+ <list type="bulleted">
+ <item>
+ <p>The trace events that are hosted by the collector may be
+ stored to file and later be loaded by selecting <c>save</c>
+ and <c>load</c> entries in the viewers <c>File</c>-menu or
+ via the <c>et_collector</c> API.</p>
+ </item>
+ <item>
+ <p>It is also possible to perform live tracing of a running
+ system by making use of the built-in trace support in
+ the Erlang emulator. These Erlang traces can be directed
+ to files or to ports. See the reference manual for
+ <c>erlang:trace/4</c>, <c>erlang:trace_pattern/3</c>,
+ <c>dbg</c> and <c>ttb</c> for more info.</p>
+ <p>There are also corresponding trace client types that can
+ read the Erlang trace data format from such files or ports.
+ The <c>et_collector:start_trace_client/3</c> function makes
+ use of these Erlang trace clients and redirects the trace
+ data to the collector.</p>
+ <p>The default collector filter converts the Erlang trace data
+ format into event-records.If you want to perform this
+ differently you can of course write your own collector
+ filter from scratch. But it may probably save you some
+ efforts if you first apply the default filter in
+ <c>et_selector:parse_event/2</c> before you apply your
+ own conversions of its output.</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Global tracing and phone home</title>
+ <p>Setting up an Erlang tracer on a set of nodes and connecting
+ trace clients to the ports of these tracers is not intuitive. In order
+ to make this it easier the Event Tracer as a notion of global
+ tracing. When used, the <c>et_collector</c> process will monitor
+ Erlang nodes and when one connects, an Erlang tracer will
+ automatically be started on the other node. A corresponding trace
+ client will also be started on the collector node in order to
+ automatically forward the trace events to the collector. Set the
+ boolean parameter <c>trace_global</c> to <c>true</c> for either the
+ <c>et_collector</c> or <c>et_viewer</c> in order to activate the
+ global tracing. There is no restriction on how many concurrent
+ (anonymous) collectors you can have, but you can only have one global
+ collector as its name is registered in <c>global</c>.</p>
+ <p>In order to further simplify the tracing you can make use of the
+ <c>et:report_event/4,5</c> (or its equivalents
+ <c>et:phone_home/4,5</c> :-). These functions are intended to be
+ invoked from other applications when there are interesting events,
+ in your application that needs to be highlighted. The functions are
+ extremely light weight as they do nothing besides returning an atom.
+ These functions are
+ specifically designed to be traced for. As the caller explicitly
+ provides the values for the event-record fields, the default collector
+ filter is able to automatically provide a customized event-record
+ without any user defined filter functions.</p>
+ <p>In normal operation the <c>et:report_event/4,5</c> calls are
+ almost for free. When tracing is needed you can either activate
+ tracing on these functions explicitly. Or you can combine the usage of
+ <c>trace_global</c> with the usage of <c>trace_pattern</c>. When set,
+ the <c>trace_pattern</c> will automatically be activated on all
+ connected nodes. </p>
+ <p>One nice thing with the <c>trace_pattern</c> is that it provides
+ a very simple way of minimizing the amount of generated trace data by
+ allowing you to explicitly control the detail level of the tracing. As
+ you may have seen the <c>et_viewer</c> have a slider called
+ <c>"Detail Level"</c> that allows you to control the detail level of the
+ trace events displayed in the viewer. On the other hand if you set a
+ low detail level in the <c>trace_pattern</c>, lots of the trace data
+ will never be generated and thus not sent over the socket to the trace
+ client and stored in the collector.</p>
+ </section>
+
+ <section>
+ <title>Viewer window</title>
+ <p>Almost all functionality available in the <c>et_viewer</c> is
+ also available via shortcuts. Which key that has the same
+ effect as selecting a menu entry is shown enclosed in
+ parentheses. For example pressing the key <c>r</c> is
+ equivalent to selecting the menu entry
+ <c>Viewer->Refresh</c>.
+ </p>
+ <p>File menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>Close Collector and all Viewers - Close the collector
+ and all viewers connected to that collector.</p>
+ </item>
+ <item>
+ <p>Close other Viewers, but keep Collector - Keep this viewer
+ and its collector, but close all other viewers connected
+ to this collector.</p>
+ </item>
+ <item>
+ <p>Close this Viewer, but keep Collector - Close this viewer,
+ but all other viewers and the collector.</p>
+ </item>
+ <item>
+ <p>Save Collector to file - Save all events stored in the
+ collector to file.</p>
+ </item>
+ <item>
+ <p>Load Collector from file - Load the collector with
+ events from a file.</p>
+ </item>
+ </list>
+ <p>Viewer menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>First - Scroll <c>this</c> viewer to the first collector
+ event.</p>
+ </item>
+ <item>
+ <p>Prev - Scroll <c>this</c> viewer one "page" backwards.
+ Normally this means that the first event displayed in the
+ viewer will be the last one and the previous <c>max_events</c>
+ events will be read from the collector.</p>
+ </item>
+ <item>
+ <p>Next - Scroll <c>this</c> viewer one "page" forward.
+ Normally this means that the last event displayed in the
+ viewer will be the first one and <c>max_events</c> more
+ events will be read from the collector.</p>
+ </item>
+ <item>
+ <p>Last - Scroll <c>this</c> viewer to the last collector event.</p>
+ </item>
+ <item>
+ <p>Refresh - Clear <c>this</c> viewer and re-read its events
+ from the collector.</p>
+ </item>
+ <item>
+ <p>Up 5 - Scroll 5 events backwards.</p>
+ </item>
+ <item>
+ <p>Down 5 - Scroll 5 events forward.</p>
+ </item>
+ <item>
+ <p>Abort search. Display all. - Switch the display mode to
+ show all events regardless of any ongoing searches.
+ Abort the searches.</p>
+ </item>
+ </list>
+ <p>Collector menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>First - Scroll <c>all</c> viewers to the first collector
+ event.</p>
+ </item>
+ <item>
+ <p>Prev - Scroll <c>all</c> viewers one "page" backwards.
+ Normally this means that the first event displayed in the
+ viewer will be the last one and the previous <c>max_events</c>
+ events will be read from the collector.</p>
+ </item>
+ <item>
+ <p>Next - Scroll <c>all</c> viewers one "page" forward.
+ Normally this means that the last event displayed in the
+ viewer will be the first one and <c>max_events</c> more
+ events will be read from the collector.</p>
+ </item>
+ <item>
+ <p>Last - Scroll <c>all</c> viewers to the last collector event.</p>
+ </item>
+ <item>
+ <p>Refresh - Clear <c>all</c> viewers and re-read their
+ events from the collector.</p>
+ </item>
+ </list>
+ <p>Filters menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>ActiveFilter (=) - Start a new viewer window with the
+ same active filter and scale as the current one.</p>
+ </item>
+ <item>
+ <p>ActiveFilter (+) - Start a new viewer window with
+ the same active filter but a larger scale than the
+ current one.</p>
+ </item>
+ <item>
+ <p>ActiveFilter (-) - Start a new viewer window with
+ the same active filter but a smaller scale than the
+ current one.</p>
+ </item>
+ <item>
+ <p>collector (0) - Start a new viewer with the collector
+ filter as active filter.</p>
+ </item>
+ <item>
+ <p>AnotherFilter (2) - If more filters are inserted into
+ the dictionary, these will turn up here as entries
+ in the <c>Filters</c> menu. The second filter will be
+ number 2, the next one number 3 etc. The names are sorted.</p>
+ </item>
+ </list>
+ <p>Slider and radio buttons:</p>
+ <list type="bulleted">
+ <item>
+ <p>Freeze - When true, this means that the viewer
+ will not read more events from the collector
+ until set to false.</p>
+ </item>
+ <item>
+ <p>Hide From=To - When true, this means that the viewer
+ will hide all events where the from-actor equals
+ to its to-actor.</p>
+ </item>
+ <item>
+ <p>Hide Unknown - When true, this means that the viewer
+ will hide all events where either of the from-actor or
+ to-actor is <c>UNKNOWN</c>.</p>
+ </item>
+ <item>
+ <p>Detail level - This slider controls the resolution
+ of the viewer. Only events with a detail level <c>smaller</c>
+ than the selected one (default=100=max) are displayed.</p>
+ </item>
+ </list>
+ <p>Other features:</p>
+ <list type="bulleted">
+ <item>
+ <p>Display details of an event - Click on the event name
+ and a new window will pop up, displaying the contents
+ of an event.</p>
+ </item>
+ <item>
+ <p>Toggle actor search - Normally the viewer will be in a
+ display mode where all events are shown. By clicking
+ on an actor name the tool will switch display mode
+ to only show events with selected actors.
+ </p>
+ <p>Click on an actor and only events with that actor
+ will be displayed. Click on another actor to include
+ that actor to the selected ones. Clicking on an already
+ selected actor will remove it from the collections of
+ selected actors. When the collection of selected actors
+ becomes empty the normal mode where all actors are shown
+ will be entered again.</p>
+ <p>Abort actor search with the <c>a</c> key or with the
+ <c>Viewer->Abort search</c> menu choice.
+ </p>
+ </item>
+ <item>
+ <p>Move actor - Drag and drop an actor by first clicking on
+ the actor name, keeping the button pressed while moving
+ the cursor to a new location and release the button where
+ the actor should be moved to.</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <p>The event-records in the ets-table are ordered by their timestamp.
+ Which timestamp that should be used is controlled via the
+ <c>event_order</c> parameter. Default is <c>trace_ts</c> which means
+ the time when the trace data was generated. <c>event_ts</c> means
+ the time when the trace data was parsed (transformed into an
+ event-record).</p>
+ </section>
+
+ <section>
+ <title>Contents viewer window</title>
+ <p>File menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>Close - Close this window.</p>
+ </item>
+ <item>
+ <p>Save - Save the contents of this window to file.</p>
+ </item>
+ </list>
+ <p>Filters menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>ActiveFilter - Start a new contents viewer window
+ with the same active filter.</p>
+ </item>
+ <item>
+ <p>AnotherFilter (2) - If more filters are inserted into
+ the dictionary, these will turn up here as entries
+ in the <c>Filters</c> menu. The second filter will be
+ number 2, the next one number 3 etc. The names are sorted.</p>
+ </item>
+ </list>
+ <p>Hide menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>Hide actor in viewer - Known actors are shown as a
+ named vertical bars in the viewer window. By hiding the
+ actor, its vertical bar will be removed and the viewer
+ will be refreshed.</p>
+ <p>Hiding the actor is only useful if the <c>max_actors</c>
+ threshold has been reached, as it then will imply that
+ the "hidden" actor will be displayed as if it were <c>"UNKNOWN"</c>.
+ If the <c>max_actors</c> threshold not have been reached,
+ the actor will re-appear as a vertical bar in the viewer.
+ </p>
+ </item>
+ <item>
+ <p>Show actor in viewer - This implies that the actor
+ will be added as a known actor in the viewer with
+ its own vertical bar.</p>
+ </item>
+ </list>
+ <p>Search menu:</p>
+ <list type="bulleted">
+ <item>
+ <p>Forward from this event - Set this event to be the first
+ event in the viewer and change its display mode to be
+ enter forward search mode. The actor of this event
+ (from, to or both) will be added to the list of selected
+ actors.
+ </p>
+ </item>
+ <item>
+ <p>Reverse from this event - Set this event to be the first
+ event in the viewer and change its display mode to be
+ enter reverse search mode. The actor of this event
+ (from, to or both) will be added to the list of selected
+ actors. Observe, that the events will be shown in reverse
+ order.
+ </p>
+ </item>
+ <item>
+ <p>Abort search. Display all - Switch the display mode
+ of the viewer to show all events regardless of any
+ ongoing searches. Abort the searches.</p>
+ </item>
+ </list>
+ </section>
+</chapter>
+