<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:erl="http://erlang.org" xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Description</title>
</head>
<body>
<div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<div class="erlang-logo-wrapper"><a href="../../../../doc/index.html"><img alt="Erlang Logo" src="../../../../doc/erlang-logo.png" class="erlang-logo"></a></div>
<p class="section-title">Event Tracer (ET)</p>
<p class="section-subtitle">User's Guide</p>
<p class="section-version">Version 1.6.4</p>
<ul class="panel-sections">
<li><a href="users_guide.html">User's Guide</a></li>
<li><a href="index.html">Reference Manual</a></li>
<li><a href="release_notes.html">Release Notes</a></li>
<li><a href="../pdf/et-1.6.4.pdf">PDF</a></li>
<li><a href="../../../../doc/index.html">Top</a></li>
</ul>
<ul class="expand-collapse-items">
<li><a href="javascript:openAllFlips()">Expand All</a></li>
<li><a href="javascript:closeAllFlips()">Contract All</a></li>
</ul>
<h3>Chapters</h3>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="et_intro.html">
Top of chapter
</a></li>
<li title="Scope and Purpose"><a href="et_intro.html#scope-and-purpose">Scope and Purpose</a></li>
<li title="Prerequisites"><a href="et_intro.html#prerequisites">Prerequisites</a></li>
<li title="About This Manual"><a href="et_intro.html#about-this-manual">About This Manual</a></li>
<li title="Where to Find More Information"><a href="et_intro.html#where-to-find-more-information">Where to Find More Information</a></li>
</ul>
</li>
<li id="no" title="Tutorial" expanded="false">Tutorial<ul>
<li><a href="et_tutorial.html">
Top of chapter
</a></li>
<li title="Visualizing Message Sequence Charts"><a href="et_tutorial.html#visualizing-message-sequence-charts">Visualizing Message Sequence Charts</a></li>
<li title="Four Modules"><a href="et_tutorial.html#four-modules">Four Modules</a></li>
<li title="The Event Tracer Interface"><a href="et_tutorial.html#the-event-tracer-interface">The Event Tracer Interface</a></li>
<li title="The Collector and Viewer"><a href="et_tutorial.html#the-collector-and-viewer">The Collector and Viewer</a></li>
<li title="The Selector"><a href="et_tutorial.html#the-selector">The Selector</a></li>
<li title="How To Put It Together"><a href="et_tutorial.html#how-to-put-it-together">How To Put It Together</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Description" expanded="true">Description<ul>
<li><a href="et_desc.html">
Top of chapter
</a></li>
<li title="Overview"><a href="et_desc.html#overview">Overview</a></li>
<li title="Filters and dictionary"><a href="et_desc.html#filters-and-dictionary">Filters and dictionary</a></li>
<li title="Trace clients"><a href="et_desc.html#trace-clients">Trace clients</a></li>
<li title="Global tracing"><a href="et_desc.html#global-tracing">Global tracing</a></li>
<li title="Viewer window"><a href="et_desc.html#viewer-window">Viewer window</a></li>
<li title="Configuration"><a href="et_desc.html#configuration">Configuration</a></li>
<li title="Contents viewer window"><a href="et_desc.html#contents-viewer-window">Contents viewer window</a></li>
</ul>
</li>
<li id="no" title="Advanced examples" expanded="false">Advanced examples<ul>
<li><a href="et_examples.html">
Top of chapter
</a></li>
<li title="A simulated Mnesia transaction"><a href="et_examples.html#a-simulated-mnesia-transaction">A simulated Mnesia transaction</a></li>
<li title="Some convenient functions used in the Mnesia transaction
example"><a href="et_examples.html#some-convenient-functions-used-in-the-mnesia-transaction-----example">Some convenient functions used in the Mnesia transaction
example</a></li>
<li title="Erlang trace of a real Mnesia transaction"><a href="et_examples.html#erlang-trace-of-a-real-mnesia-transaction">Erlang trace of a real Mnesia transaction</a></li>
<li title="Erlang trace of Megaco startup"><a href="et_examples.html#erlang-trace-of-megaco-startup">Erlang trace of Megaco startup</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>3 Description</h1>
<h3><span onMouseOver="document.getElementById('ghlink-overview-idm281472813805112').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-overview-idm281472813805112').style.visibility = 'hidden';"><span id="ghlink-overview-idm281472813805112" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L36" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="overview" href="#overview">3.1
Overview</a></span></h3>
<p>The two major components of the <span class="code">Event Tracer (ET)</span> tool
is a graphical sequence chart viewer (<span class="code">et_viewer</span>) and its
backing storage (<span class="code">et_collector</span>). One <span class="code">Collector</span> may be
used as backing storage for several simultaneous <span class="code">Viewers</span>
where each one may display a different view of the same trace
data.</p>
<p>The interface between the <span class="code">Collector</span> and its
<span class="code">Viewers</span> is public in order to enable other types of
<span class="code">Viewers</span>. However in the following text we will focus on
usage of the <span class="code">et_viewer</span>.</p>
<p>The main start function is <span class="code">et_viewer:start/1</span>. By
default it will start both an <span class="code">et_collector</span> and an
<span class="code">et_viewer</span>:</p>
<p></p>
<div class="example"><pre>% erl -pa et/examples
Erlang R13B03 (erts-5.7.4) [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false]
Eshell V5.7.4 (abort with ^G)
1> {ok, Viewer} = et_viewer:start([]).
{ok,<0.40.0>}</pre></div>
<p>A <span class="code">Viewer</span> gets trace <span class="code">Events</span> from its
<span class="code">Collector</span> by polling it regularly for more <span class="code">Events</span> to
display. <span class="code">Events</span> are for example reported to the
<span class="code">Collector</span> with <span class="code">et_collector:report_event/6</span>:</p>
<div class="example"><pre>2> Collector = et_viewer:get_collector_pid(Viewer).
<0.39.0>
3> et_collector:report_event(Collector, 60, my_shell, mnesia_tm, start_outer,
3> "Start outer transaction"),
3> et_collector:report_event(Collector, 40, mnesia_tm, my_shell, new_tid,
3> "New transaction id is 4711"),
3> et_collector:report_event(Collector, 20, my_shell, mnesia_locker, try_write_lock,
3> "Acquire write lock for {my_tab, key}"),
3> et_collector:report_event(Collector, 10, mnesia_locker, my_shell, granted,
3> "You got the write lock for {my_tab, key}"),
3> et_collector:report_event(Collector, 60, my_shell, do_commit,
3> "Perform transaction commit"),
3> et_collector:report_event(Collector, 40, my_shell, mnesia_locker, release_tid,
3> "Release all locks for transaction 4711"),
3> et_collector:report_event(Collector, 60, my_shell, mnesia_tm, delete_transaction,
3> "End of outer transaction"),
3> et_collector:report_event(Collector, 20, my_shell, end_outer,
3> "Transaction returned {atomic, ok}").
{ok,{table_handle,<0.39.0>,16402,trace_ts,
#Fun<et_collector.0.62831470>}}</pre></div>
<p>This actually is a simulation of the process <span class="code">Events</span>
caused by a <span class="code">Mnesia</span> transaction that writes a record in a local
table:</p>
<div class="example"><pre>mnesia:transaction(fun() -> mnesia:write({my_tab, key, val}) end).</pre></div>
<p>At this stage when we have a couple of <span class="code">Events</span>, it is time to
show how it looks like in the graphical interface of
<span class="code">et_viewer</span>:</p>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans.png" class="doc-image">
<p class="doc-image-caption">Figure
3.1:
A simulated Mnesia transaction which writes one record</p>
</div>
<p>In the sequence chart, the actors (which symbolically has
performed the <span class="code">Event</span>) 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>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans_move_actor.png" class="doc-image">
<p class="doc-image-caption">Figure
3.2:
Two actors has switched places</p>
</div>
<p>An <span class="code">Event</span> 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 <span class="code">Event</span> can be shown by clicking (press
and release the mouse button 1) on the event label text or on the
arrow. When doing that a <span class="code">Contents Viewer</span> window pops up. It
may look like this:</p>
<p></p>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans_write_lock.png" class="doc-image">
<p class="doc-image-caption">Figure
3.3:
Details of a write lock message</p>
</div>
<h3><span onMouseOver="document.getElementById('ghlink-filters-and-dictionary-idm281472813677016').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-filters-and-dictionary-idm281472813677016').style.visibility = 'hidden';"><span id="ghlink-filters-and-dictionary-idm281472813677016" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L132" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="filters-and-dictionary" href="#filters-and-dictionary">3.2
Filters and dictionary</a></span></h3>
<p>The <span class="code">Event Tracer (ET)</span> uses named filters in various
contexts. An Event Trace filter is an <span class="code">Erlang fun</span> that takes
some trace data as input and returns a possibly modified version
of it:
</p>
<p></p>
<div class="example"><pre>filter(TraceData) -> false | true | {true, NewEvent}
TraceData = Event | erlang_trace_data()
Event = #event{}
NewEvent = #event{}</pre></div>
<p>The interface of the filter function is the same as the the
filter functions for the good old <span class="code">lists:filtermap/2</span>. If the filter
returns <span class="code">false</span> it means that the trace data should silently
be dropped. <span class="code">true</span> means that the trace data data already is
an <span class="code">Event Record</span> and that it should be kept as it is.
<span class="code">true</span> means that the <span class="code">TraceData</span> already is an <span class="code">Event
Record</span> and that it should be kept as it is. <span class="code">{true,
NewEvent}</span> means that the original trace data should be
replaced with <span class="code">Event</span>. This provides means to get rid of
unwanted <span class="code">Events</span> as well as enabling alternate views of an
<span class="code">Event</span>.</p>
<p>The first filter that the trace data is exposed for is the
<span class="code">Collector Filter</span>. When a trace <span class="code">Event</span> is reported with
<span class="code">et_collector:report/2</span> (or
<span class="code">et_collector:report_event/5,6</span>) the first thing that
happens, is that a message is sent to the <span class="code">Collector</span> process
to fetch a handle that contains some useful stuff, such as the
<span class="code">Collector Filter Fun</span> and an Ets table identifier. Then the
<span class="code">Collector Filter Fun</span> is applied and if it returns
<span class="code">true</span> (or <span class="code">{true, NewEvent}</span>), the <span class="code">Event</span> will be stored
in an Ets table. As an optimization, subsequent calls to
<span class="code">et_collector:report</span>-functions can use the handle directly
instead of the <span class="code">Collector Pid</span>.</p>
<p>All filters (registered in a <span class="code">Collector</span> or in a
<span class="code">Viewer</span>) must be able to handle an <span class="code">Event record</span> as
input. The <span class="code">Collector Filter</span> (that is the filter named
<span class="code">all</span>) is a little bit special, as its input also may be raw
<span class="code">Erlang Trace Data</span></p>
<p>The <span class="code">Collector</span> manages a key/value based dictionary,
where the filters are stored. Updates of the dictionary is
propagated to all subscribing processes. When a <span class="code">Viewer</span> is
started it is registered as a subscriber of dictionary
updates.</p>
<p>In each <span class="code">Viewer</span> there is only one filter that is active
and all trace <span class="code">Events</span> that the <span class="code">Viewer</span> gets from the
<span class="code">Collector</span> will pass thru that filter. By writing clever
filters it is possible to customize how the <span class="code">Events</span> looks
like in the viewer. The following filter in
<span class="code">et/examples/et_demo.erl</span> replaces the actor names
<span class="code">mnesia_tm</span> and <span class="code">mnesia_locker</span> and leaves everything
else in the record as it was:</p>
<p></p>
<div class="example"><pre>mgr_actors(E) when is_record(E, event) ->
Actor = fun(A) ->
case A of
mnesia_tm -> trans_mgr;
mnesia_locker -> lock_mgr;
_ -> A
end
end,
{true, E#event{from = Actor(E#event.from),
to = Actor(E#event.to),
contents = [{orig_from, E#event.from},
{orig_to, E#event.to},
{orig_contents, E#event.contents}]}}.</pre></div> <p>If we now add the filter to the running <span class="code">Collector</span>:</p>
<p></p>
<div class="example"><pre>4> Fun = fun(E) -> et_demo:mgr_actors(E) end.
#Fun<erl_eval.6.13229925>
5> et_collector:dict_insert(Collector, {filter, mgr_actors}, Fun).
ok</pre></div>
<p>you will see that the <span class="code">Filter</span> menu in all viewers have
got a new entry called <span class="code">mgr_actors</span>. Select it, and a new
<span class="code">Viewer</span> window will pop up:</p>
<p></p>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans_mgr_actors.png" class="doc-image">
<p class="doc-image-caption">Figure
3.4:
The same trace data in a different view</p>
</div>
<p>In order to see the nitty gritty details of an <span class="code">Event</span> you
may click on the <span class="code">Event</span> in order to start a <span class="code">Contents
Viewer</span> for that <span class="code">Event</span>. In the <span class="code">Contents Viewer</span>
there also is a filter menu that enables inspection of the
<span class="code">Event</span> from other views than the one selected in the
viewer. A click on the <span class="code">new_tid</span> <span class="code">Event</span> will cause a
<span class="code">Contents Viewer</span> window to pop up, showing the <span class="code">Event</span>
in the <span class="code">mgr_actors</span> view:</p>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans_contents_viewer_mgr_actors.png" class="doc-image">
<p class="doc-image-caption">Figure
3.5:
The trace Event in the mgr_actors view</p>
</div>
<p>Select the <span class="code">all</span> entry in the <span class="code">Filters</span> menu
and a new <span class="code">Contents Viewer window</span> will pop up showing the
same trace <span class="code">Event</span> in the collectors view:</p>
<div class="doc-image-wrapper">
<img alt="IMAGE MISSING" src="sim_trans_contents_viewer_collector.png" class="doc-image">
<p class="doc-image-caption">Figure
3.6:
The same trace Event in the collectors view</p>
</div>
<h3><span onMouseOver="document.getElementById('ghlink-trace-clients-idm281472813614968').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-trace-clients-idm281472813614968').style.visibility = 'hidden';"><span id="ghlink-trace-clients-idm281472813614968" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L241" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="trace-clients" href="#trace-clients">3.3
Trace clients</a></span></h3>
<p>As you have seen, it is possible to use the
<span class="code">et_collector:report_event/5,6</span> 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 <span class="code">Collector</span> with it. You may replace the default
<span class="code">Collector Filter</span> with a filter that converts new exciting
trace data formats to <span class="code">Event Records</span> or you may convert it
to an <span class="code">Event Record</span> before you invoke
<span class="code">et_collector:report/2</span> and then rely on the default
<span class="code">Collector Filter</span> to handle the new format.</p>
<p>There are also existing functions in the API that reads from
various sources and calls <span class="code">et_collector:report/2</span>:</p>
<ul>
<li>
<p>The trace <span class="code">Events</span> that are hosted by the <span class="code">Collector</span> may be
stored to file and later be loaded by selecting <span class="code">save</span>
and <span class="code">load</span> entries in the <span class="code">Viewers</span> <span class="code">File</span> menu
or via the <span class="code">et_collector</span> API.</p>
</li>
<li>
<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
<span class="code">erlang:trace/4</span>, <span class="code">erlang:trace_pattern/3</span>,
<span class="code">dbg</span> and <span class="code">ttb</span> 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 <span class="code">et_collector:start_trace_client/3</span> function makes
use of these Erlang trace clients and redirects the trace data
to the <span class="code">Collector</span>.</p>
<p>The default <span class="code">Collector Filter</span> converts the raw Erlang
trace data format into <span class="code">Event Records</span>. If you want to
perform this differently you can of course write your own
<span class="code">Collector Filter</span> from scratch. But it may probably save
you some efforts if you first apply the default filter in
<span class="code">et_selector:parse_event/2</span> before you apply your own
conversions of its output.</p>
</li>
</ul>
<h3><span onMouseOver="document.getElementById('ghlink-global-tracing-idm281472813597640').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-global-tracing-idm281472813597640').style.visibility = 'hidden';"><span id="ghlink-global-tracing-idm281472813597640" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L290" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="global-tracing" href="#global-tracing">3.4
Global tracing</a></span></h3>
<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 <span class="code">Event Tracer</span> has a notion
of global tracing. When used, the <span class="code">et_collector</span> process will
monitor Erlang nodes and when one connects, an Erlang tracer will
automatically be started on the newly connected node. A
corresponding trace client will also be started on the
<span class="code">Collector</span> node in order to automatically forward the trace
<span class="code">Events</span> to the <span class="code">Collector</span>. Set the boolean parameter
<span class="code">trace_global</span> to <span class="code">true</span> for either the
<span class="code">et_collector</span> or <span class="code">et_viewer</span> 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
<strong>global</strong> <span class="code">Collector</span> as its name is registered in
<span class="code">global</span>.</p>
<p>In order to further simplify the tracing, you can make use of
the <span class="code">et:trace_me/4,5</span> functions. These functions are intended
to be invoked from other applications when there are interesting
<span class="code">Events</span>, 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 <span class="code">Event Record</span> fields, the
default <span class="code">Collector Filter</span> is able to automatically provide a
customized <span class="code">Event Record</span> without any user defined filter
functions.</p>
<p>In normal operation, the <span class="code">et:trace_me/4,5</span> 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
<span class="code">trace_global</span> with the usage of <span class="code">trace_pattern</span>. When
set, the <span class="code">trace_pattern</span> will automatically be activated on
all connected nodes. </p>
<p>One nice thing with the <span class="code">trace_pattern</span> 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 <span class="code">et_viewer</span> have a
slider called <span class="code">"Detail Level"</span> that allows you to control the
detail level of the trace <span class="code">Events</span> displayed in the
<span class="code">Viewer</span>. On the other hand if you set a low detail level in
the <span class="code">trace_pattern</span>, lots of the trace data will never be
generated and thus not sent over the socket to the trace client
and stored in the <span class="code">Collector</span>.</p>
<h3><span onMouseOver="document.getElementById('ghlink-viewer-window-idm281472813581672').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-viewer-window-idm281472813581672').style.visibility = 'hidden';"><span id="ghlink-viewer-window-idm281472813581672" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L340" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="viewer-window" href="#viewer-window">3.5
Viewer window</a></span></h3>
<p>Almost all functionality available in the <span class="code">et_viewer</span> 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 <span class="code">r</span> is equivalent to selecting the
menu entry <span class="code">Viewer->Refresh</span>.</p>
<p>File menu:</p>
<ul>
<li>
<p><span class="code">Clear all events in the Collector</span> - Deletes all
<span class="code">Events</span> stored in the <span class="code">Collector</span> and notifies all
connected <span class="code">Viewers</span> about this.</p>
</li>
<li>
<p><span class="code">Load events to the Collector from file</span> - Loads the
<span class="code">Collector</span> with <span class="code">Events</span> from a file and notifies
all connected <span class="code">Viewers</span> about this.</p>
</li>
<li>
<p><span class="code">Save all events in the Collector to file</span> - Saves all
<span class="code">Events</span> stored in the <span class="code">Collector</span> to file.</p>
</li>
<li>
<p><span class="code">Print setup</span> - Enables editing of printer setting,
such as paper and layout.</p>
</li>
<li>
<p><span class="code">Print current page</span> - Prints the events on the
current page. The page size is dependent of the selected paper
type.</p>
</li>
<li>
<p><span class="code">Print all pages</span> - Prints all events. The page size
is dependent of the selected paper type.</p>
</li>
<li>
<p><span class="code">Close this Viewer</span> - Closes this <span class="code">Viewer</span>
window, but keeps all other <span class="code">Viewers</span> windows and the
<span class="code">Collector</span> process.</p>
</li>
<li>
<p><span class="code">Close other Viewers, but this</span> - Keeps this
<span class="code">Viewer</span> window and its <span class="code">Collector</span> process, but
closes all other <span class="code">Viewers</span> windowsconnected to the same
<span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Close all Viewers and the Collector</span> - Closes the
<span class="code">Collector</span> and all <span class="code">Viewers</span> connected to it.</p>
</li>
</ul>
<p>Viewer menu:</p>
<ul>
<li>
<p><span class="code">First</span> - Scrolls <span class="code">this</span> viewer to the first
<span class="code">Event</span> in the <span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Last</span> - Scrolls <span class="code">this</span> viewer to the last
<span class="code">Event</span> in the <span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Prev</span> - Scrolls <span class="code">this</span> viewer one page
backwards.</p>
</li>
<li>
<p><span class="code">Next</span> - Scrolls <span class="code">this</span> viewer one page
forward.</p>
</li>
<li>
<p><span class="code">Refresh</span> - Clears <span class="code">this</span> viewer and re-read its
<span class="code">Events</span> from the <span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Up</span> - Scrolls a few <span class="code">Events</span> backwards.</p>
</li>
<li>
<p><span class="code">Down</span> - Scrolls a few <span class="code">Events</span> forward.</p>
</li>
<li>
<p><span class="code">Display all actors.</span> - Reset the settings for hidden
and/or highlighted actors.</p>
</li>
</ul>
<p>Collector menu:</p>
<ul>
<li>
<p><span class="code">First</span> - Scrolls<span class="code">all</span> viewers to the first
<span class="code">Event</span> in the <span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Last</span> - Scrolls <span class="code">all</span> viewers to the last
<span class="code">Event</span> in the <span class="code">Collector</span>.</p>
</li>
<li>
<p><span class="code">Prev</span> - Scrolls <span class="code">all</span> viewers one page
backwards.</p>
</li>
<li>
<p><span class="code">Next</span> - Scrolls <span class="code">all</span> viewers one page
forward.</p>
</li>
<li>
<p><span class="code">Refresh</span> - Clears <span class="code">all</span> viewers and re-read
their <span class="code">Events</span> from the <span class="code">Collector</span>.</p>
</li>
</ul>
<p>Filters and scaling menu:</p>
<ul>
<li>
<p><span class="code">ActiveFilter (=)</span> - Starts a new <span class="code">Viewer</span> window
with the same active filter and scale as the current one.</p>
</li>
<li>
<p><span class="code">ActiveFilter (+)</span> - Starts a new <span class="code">Viewer</span> window
with the same active filter but a larger scale than the
current one.</p>
</li>
<li>
<p><span class="code">ActiveFilter (-)</span> - Starts a new <span class="code">Viewer </span>window
with the same active filter but a smaller scale than the
current one.</p>
</li>
<li>
<p><span class="code">all (0)</span> - Starts a new <span class="code">Viewer</span> with the
<span class="code">Collector Filter</span> as active filter. It will cause all
events in the collector to be viewed.</p>
</li>
<li>
<p><span class="code">AnotherFilter (2)</span> - If more filters are inserted
into the dictionary, these will turn up here as entries in the
<span class="code">Filters</span> menu. The second filter will get the shortcut
number 2, the next one number 3 etc. The names are sorted.</p>
</li>
</ul>
<p>Slider and radio buttons:</p>
<ul>
<li>
<p><span class="code">Hide From=To</span> - When true, this means that the
<span class="code">Viewer</span> will hide all <span class="code">Events</span> where the from-actor
equals to its to-actor. These events are sometimes called
actions.</p>
</li>
<li>
<p><span class="code">Hide (excluded actors)</span> - When true, this means that
the <span class="code">Viewer</span> will hide all <span class="code">Events</span> whose actors are
marked as excluded. Excluded actors are normally enclosed in
round brackets when they are displayed inthe
<span class="code">Viewer</span>.</p>
</li>
<li>
<p><span class="code">Detail level</span> - This slider controls the resolution
of the <span class="code">Viewer</span>. Only <span class="code">Events</span> with a detail level
<span class="code">smaller</span> than the selected one (default=100=max) are
displayed.</p>
</li>
</ul>
<p>Other features:</p>
<ul>
<li>
<p><span class="code">Vertical scroll</span> - Use mouse wheel and up/down arrows
to scroll little. Use page up/down and home/end buttons to
scroll more.</p>
</li>
<li>
<p><span class="code">Display details of an event</span> - Left mouse click on
the event label or the arrowand a new <span class="code">Contents Viewer</span>
window will pop up, displaying the contents of an
<span class="code">Event</span>.</p>
</li>
<li>
<p><span class="code">Highlight actor (toggle)</span> - Left mouse click on the
actor name tag. The actor name will be enclosed in square
brackets <span class="code">[]</span>. When one or more actors are highlighted,
only events related to those actors are displayed. All others
are hidden.</p>
</li>
<li>
<p><span class="code">Exclude actor (toggle)</span> - Right mouse click on the
actor name tag. The actor name will be enclosed in round
brackets <span class="code">()</span>. When an actor is excluded, all events
related to this actor is hidden. If the checkbox <span class="code">Hide
(excluded actors)</span> is checked, even the name tags and
corresponding vertical line of excluded actors will be
hidden.</p>
</li>
<li>
<p><span class="code">Move actor</span> - Left mouse button drag and drop on
actor name tag. Move the 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>
</li>
<li>
<p><span class="code">Display all actors</span> - Press the 'a' button. Reset the
settings for hidden and/or highlighted actors.</p>
</li>
</ul>
<h3><span onMouseOver="document.getElementById('ghlink-configuration-idm281472813300232').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-configuration-idm281472813300232').style.visibility = 'hidden';"><span id="ghlink-configuration-idm281472813300232" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L584" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="configuration" href="#configuration">3.6
Configuration</a></span></h3>
<p>The <span class="code">Event Records</span> in the Ets table are ordered by their
timestamp. Which timestamp that should be used is controlled via
the <span class="code">event_order</span> parameter. Default is <span class="code">trace_ts</span> which
means the time when the trace data was generated. <span class="code">event_ts</span>
means the time when the trace data was parsed (transformed into an
<span class="code">Event Record</span>).</p>
<h3><span onMouseOver="document.getElementById('ghlink-contents-viewer-window-idm281472813296232').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-contents-viewer-window-idm281472813296232').style.visibility = 'hidden';"><span id="ghlink-contents-viewer-window-idm281472813296232" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/lib/et/doc/src/et_desc.xmlsrc#L595" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="contents-viewer-window" href="#contents-viewer-window">3.7
Contents viewer window</a></span></h3>
<p>File menu:</p>
<ul>
<li>
<p><span class="code">Close</span> - Close this window.</p>
</li>
<li>
<p><span class="code">Save</span> - Save the contents of this window to file.</p>
</li>
</ul>
<p>Filters menu:</p>
<ul>
<li>
<p><span class="code">ActiveFilter</span> - Start a new <span class="code">Contents Viewer
window</span> with the same active filter.</p>
</li>
<li>
<p><span class="code">AnotherFilter (2)</span> - If more filters are inserted
into the dictionary, these will turn up here as entries in the
<span class="code">Filters</span> menu. The second filter will be number 2, the
next one number 3 etc. The names are sorted.</p>
</li>
</ul>
<p>Hide menu:</p>
<ul>
<li>
<p><span class="code">Hide actor in viewer</span> - Known actors are shown as a
named vertical bars in the <span class="code">Viewer</span> window. By hiding the
actor, its vertical bar will be removed and the <span class="code">Viewer</span>
will be refreshed.</p>
<p><span class="code">Hiding the actor</span> is only useful if the
<span class="code">max_actors</span> threshold has been reached, as it then will
imply that the "hidden" actor will be displayed as if it were
<span class="code">"UNKNOWN"</span>. If the <span class="code">max_actors</span> threshold not have
been reached, the actor will re-appear as a vertical bar in
the <span class="code">Viewer</span>.</p>
</li>
<li>
<p><span class="code">Show actor in viewer</span> - This implies that the actor
will be added as a known actor in the <span class="code">Viewer</span> with its
own vertical bar.</p>
</li>
</ul>
<p>Search menu:</p>
<ul>
<li>
<p><span class="code">Forward from this event</span> - 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>
</li>
<li>
<p><span class="code">Reverse from this event</span> - Set this event to be the
first <span class="code">Event</span> in the <span class="code">Viewer</span> and change its display
mode to be enter reverse search mode. The actor of this
<span class="code">Event</span> (from, to or both) will be added to the list of
selected actors. Observe, that the <span class="code">Events</span> will be shown
in reverse order.</p>
</li>
<li>
<p><span class="code">Abort search. Display all</span> - Switch the display mode
of the <span class="code">Viewer</span> to show all <span class="code">Events</span> regardless of
any ongoing searches. Abort the searches.</p>
</li>
</ul>
</div>
<div class="footer">
<hr>
<p>Copyright © 2002-2019 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div>
<script type="text/javascript">window.__otpTopDocDir = '../../../../doc/js/';</script><script type="text/javascript" src="../../../../doc/js/highlight.js"></script>
</body>
</html>
