diff options
Diffstat (limited to 'lib/et/doc/src/et_architecture.xml')
| -rw-r--r-- | lib/et/doc/src/et_architecture.xml | 554 |
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åkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Hå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> + |