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, 0 insertions, 554 deletions
diff --git a/lib/et/doc/src/et_architecture.xml b/lib/et/doc/src/et_architecture.xml deleted file mode 100644 index 44e262db96..0000000000 --- a/lib/et/doc/src/et_architecture.xml +++ /dev/null @@ -1,554 +0,0 @@ -<?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> - |