aboutsummaryrefslogtreecommitdiffstats
path: root/lib/observer/doc/src/ttb_ug.xml
diff options
context:
space:
mode:
authortmanevik <[email protected]>2015-11-23 18:27:25 +0100
committerDan Gudmundsson <[email protected]>2016-02-22 09:38:19 +0100
commite6b2edc8027c40db4c12f8f081648cda4634f9f7 (patch)
treef0ec5f7b023f51c62ab6a383fa650cacbd85770a /lib/observer/doc/src/ttb_ug.xml
parent82a835d94be7ee5e98d101a29999fedaf6cd75fe (diff)
downloadotp-e6b2edc8027c40db4c12f8f081648cda4634f9f7.tar.gz
otp-e6b2edc8027c40db4c12f8f081648cda4634f9f7.tar.bz2
otp-e6b2edc8027c40db4c12f8f081648cda4634f9f7.zip
Observer: Editorial changes in documentation
Diffstat (limited to 'lib/observer/doc/src/ttb_ug.xml')
-rw-r--r--lib/observer/doc/src/ttb_ug.xml1032
1 files changed, 538 insertions, 494 deletions
diff --git a/lib/observer/doc/src/ttb_ug.xml b/lib/observer/doc/src/ttb_ug.xml
index e2a28d67d0..34591ae8de 100644
--- a/lib/observer/doc/src/ttb_ug.xml
+++ b/lib/observer/doc/src/ttb_ug.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2002</year><year>2013</year>
+ <year>2002</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -32,78 +32,85 @@
<section>
<title>Introduction</title>
- <p>The Trace Tool Builder is a base for building trace tools for
- single node or distributed erlang systems. It requires the
- <c>runtime_tools</c> application to be available on the traced
+ <p>Trace Tool Builder is a base for building trace tools for
+ single node or distributed Erlang systems. It requires the
+ Runtime_Tools application to be available on the traced
node.
</p>
- <p>The main features of the Trace Tool Builder are:</p>
+ <p>The following are the main features of Trace Tool Builder:</p>
<list type="bulleted">
- <item>Start tracing to file ports on several nodes with one
+ <item>Start tracing to file ports on many nodes with one
function call.</item>
- <item>Write additional information to a trace information file,
+ <item>Write more information to a trace information file,
which is read during formatting.</item>
- <item>Restoring of previous configuration by maintaining a
+ <item>Restore previous configuration by maintaining a
history buffer and handling configuration files.</item>
- <item>Some simple support for sequential tracing.</item>
- <item>Formatting of binary trace logs and merging of logs from
+ <item>Provide some simple support for sequential tracing.</item>
+ <item>Format binary trace logs and merge logs from
multiple nodes.</item>
</list>
- <p>The intention of the Trace Tool Builder is to serve
- as a base for tailor made trace tools, but you may use it directly
- from the erlang shell (it may mimic <c>dbg</c> behaviour while
- still providing useful additions like match specification shortcuts).
- The application only
- allows the use of file port tracer, so if you would like
- to use other types of trace clients you will be better off
- using <c>dbg</c> directly instead.</p>
+ <p>The intention of Trace Tool Builder is to serve
+ as a base for tailor-made trace tools, but it can also be used directly
+ from the Erlang shell (it can mimic <c>dbg</c> behaviour while
+ still providing useful additions, such as match specification shortcuts).
+ Trace Tool Builder only allows the use of file port tracer, so to use
+ other types of trace clients it is better to use <c>dbg</c> directly.</p>
</section>
<section>
<title>Getting Started</title>
- <p>The <c>ttb</c> module is the interface to all functions in the
- Trace Tool Builder. To get started the least you need to do is to
- start a tracer with <c>ttb:tracer/0/1/2</c>, and set the required
- trace flags on the processes you want to trace with
- <c>ttb:p/2</c>. Then, when the tracing is completed, you must stop
- the tracer with <c>ttb:stop/0/1</c> and format the trace log with
- <c>ttb:format/1/2</c> (as long as there is anything to format, of
- course).
+ <p>Module <c>ttb</c> is the interface to all functions in
+ Trace Tool Builder.</p>
+ <p>To get started, the least you need to do is to
+ start a tracer with
+ <seealso marker="ttb#tracer/0"><c>ttb:tracer/0,1,2</c></seealso>,
+ and set the required
+ trace flags on the processes you want to trace with
+ <seealso marker="ttb#p/2"><c>ttb:p/2</c></seealso>.</p>
+ <p>When the tracing is completed, stop the tracer with
+ <seealso marker="ttb#stop/0"><c>ttb:stop/0,1</c></seealso>
+ and format the trace log with
+ <seealso marker="ttb#format/1"><c>ttb:format/1,2</c></seealso>
+ (if there is anything to format).
</p>
- <p><c>ttb:tracer/0/1/2</c> opens a trace port on each node
- that shall be traced. By default, trace messages are written
- to binary files on remote nodes(the binary trace log).
- </p>
- <p><c>ttb:p/2</c> specifies which processes shall be
- traced. Trace flags given in this call specify what to trace on
- each process. You can call this function several times if you like
- different trace flags to be set on different processes.
- </p>
- <p>If you want to trace function calls (i.e. if you have the
- <c>call</c> trace flag set on any of your processes), you must
+ <p><em>Useful functions:</em></p>
+ <taglist>
+ <tag><c>ttb:tracer/0,1,2</c></tag>
+ <item><p>Opens a trace port on each node to be traced. By default,
+ trace messages are written to binary files on remote nodes (the
+ binary trace log).</p></item>
+ <tag><c>ttb:p/2</c></tag>
+ <item><p>Specifies the processes to be traced. Trace flags specified
+ in this call specify what to trace on each process. This function can be
+ called many times if you like different trace flags to be set on different
+ processes.</p></item>
+ <tag><c>ttb:tp/2,3,4</c> or <c>ttb:tpl/2,3,4</c></tag>
+ <item><p>If you want to trace function calls (that is, if you have
+ trace flag <c>call</c> set on any process), you must
also set trace patterns on the required function(s) with
- <c>ttb:tp</c> or <c>ttb:tpl</c>. A function is only traced if it
- has a trace pattern. The trace pattern specifies how to trace the
+ <seealso marker="ttb#/0"><c>ttb:tp/2,3,4</c></seealso> or
+ <seealso marker="ttb#/0"><c>ttb:tpl/2,3,4</c></seealso>.
+ A function is only traced
+ if it has a trace pattern. The trace pattern specifies how to trace the
function by using match specifications. Match specifications are
- described in the User's Guide for the erlang runtime system
- <c>erts</c>.
- </p>
- <p><c>ttb:stop/0/1</c> stops tracing on all nodes, deletes all
- trace patterns and flushes the trace port buffer.
- </p>
- <p><c>ttb:format/1/2</c> translates the binary trace logs into
- something readable. By default <c>ttb</c> presents each trace
- message as a line of text, but you can also write your own handler
- to make more complex interpretations of the trace information. A
- trace log can even be presented graphically via the Event Tracer
- application. Note that if you give the <c>format</c> option to
- <c>ttb:stop/1</c> the formatting is automatically done when
- stopping <c>ttb</c>.
- </p>
-
+ described in the
+ <seealso marker="erts:users_guide">ERTS User's Guide</seealso>.</p></item>
+ <tag><c>ttb:stop/0,1</c></tag>
+ <item><p>Stops tracing on all nodes, deletes all trace patterns, and
+ flushes the trace port buffer.</p></item>
+ <tag><c>ttb:format/1/2</c></tag>
+ <item><p>Translates the binary trace logs into something readable.
+ By default, <c>ttb</c> presents each trace message as a line of text,
+ but you can also write your own handler to make more complex interpretations
+ of the trace information. A trace log can also be presented graphically
+ with application Event Tracer (ET).</p>
+ <p>If option <c>format</c> is specified to <c>ttb:stop/1</c>, the formatting
+ is automatically done when stopping <c>ttb</c>.</p></item>
+ </taglist>
+
<section>
- <title>Example: Tracing the local node from the erlang shell</title>
- <p>This small module is used in the example:</p>
+ <title>Tracing Local Node from Erlang Shell</title>
+ <p>The following small module is used in the subsequent example:</p>
<code type="none">
-module(m).
-export([f/0]).
@@ -114,25 +121,25 @@ f() ->
From ! {self(),Now}
end. </code>
<p>The following example shows the basic use of <c>ttb</c> from
- the erlang shell. Default options are used both for starting the
- tracer and for formatting (the custom fetch dir is however provided).
- This gives a trace log named <c>Node-ttb</c> in the newly-created
- directory, where <c>Node</c> is the name of the node. The
+ the Erlang shell. Default options are used both for starting the
+ tracer and for formatting (the custom fetch directory is however provided).
+ This gives a trace log named <c>Node-ttb</c> in the newly created
+ directory, where <c>Node</c> is the node name. The
default handler prints the formatted trace messages in the
- shell.</p>
- <code type="none"><![CDATA[
+ shell:</p>
+ <pre>
(tiger@durin)47> %% First I spawn a process running my test function
-(tiger@durin)47> Pid = spawn(m,f,[]).
-<0.125.0>
+(tiger@durin)47> <input>Pid = spawn(m,f,[]).</input>
+&lt;0.125.0>
(tiger@durin)48>
(tiger@durin)48> %% Then I start a tracer...
-(tiger@durin)48> ttb:tracer().
+(tiger@durin)48> <input>ttb:tracer().</input>
{ok,[tiger@durin]}
(tiger@durin)49>
(tiger@durin)49> %% and activate the new process for tracing
(tiger@durin)49> %% function calls and sent messages.
-(tiger@durin)49> ttb:p(Pid,[call,send]).
-{ok,[{<0.125.0>,[{matched,tiger@durin,1}]}]}
+(tiger@durin)49> <input>ttb:p(Pid,[call,send]).</input>
+{ok,[{&lt;0.125.0>,[{matched,tiger@durin,1}]}]}
(tiger@durin)50>
(tiger@durin)50> %% Here I set a trace pattern on erlang:now/0
(tiger@durin)50> %% The trace pattern is a simple match spec
@@ -140,33 +147,33 @@ f() ->
(tiger@durin)50> %% traced. Refer to the reference_manual for
(tiger@durin)50> %% the full list of match spec shortcuts
(tiger@durin)50> %% available.
-(tiger@durin)51> ttb:tp(erlang,now,return).
+(tiger@durin)51> <input>ttb:tp(erlang,now,return).</input>
{ok,[{matched,tiger@durin,1},{saved,1}]}
(tiger@durin)52>
(tiger@durin)52> %% I run my test (i.e. send a message to
(tiger@durin)52> %% my new process)
-(tiger@durin)52> Pid ! self().
-<0.72.0>
+(tiger@durin)52> <input>Pid ! self().</input>
+&lt;0.72.0>
(tiger@durin)53>
(tiger@durin)53> %% And then I have to stop ttb in order to flush
(tiger@durin)53> %% the trace port buffer
-(tiger@durin)53> ttb:stop([return, {fetch_dir, "fetch"}]).
+(tiger@durin)53> <input>ttb:stop([return, {fetch_dir, "fetch"}]).</input>
{stopped, "fetch"}
(tiger@durin)54>
(tiger@durin)54> %% Finally I format my trace log
-(tiger@durin)54> ttb:format("fetch").
-({<0.125.0>,{m,f,0},tiger@durin}) call erlang:now()
-({<0.125.0>,{m,f,0},tiger@durin}) returned from erlang:now/0 ->
+(tiger@durin)54> <input>ttb:format("fetch").</input>
+({&lt;0.125.0>,{m,f,0},tiger@durin}) call erlang:now()
+({&lt;0.125.0>,{m,f,0},tiger@durin}) returned from erlang:now/0 ->
{1031,133451,667611}
-({<0.125.0>,{m,f,0},tiger@durin}) <0.72.0> !
-{<0.125.0>,{1031,133451,667611}}
-ok ]]></code>
+({&lt;0.125.0>,{m,f,0},tiger@durin}) &lt;0.72.0> !
+{&lt;0.125.0>,{1031,133451,667611}}
+ok</pre>
</section>
<section>
- <title>Example: Build your own tool</title>
- <p>This small example shows a simple tool for "debug tracing",
- i.e. tracing of function calls with return values.</p>
+ <title>Build Your Own Tool</title>
+ <p>The following example shows a simple tool for "debug tracing",
+ that is, tracing of function calls with return values:</p>
<code type="none"><![CDATA[
-module(mydebug).
-export([start/0,trc/1,stop/0,format/1]).
@@ -228,124 +235,127 @@ do_print(Out,{trace_ts,P,return_from,{M,F,A},R,Ts},N) ->
"Return value :~p~n~n",
[N,Ts,P,M,F,A,R]). ]]></code>
<p>To distinguish trace logs produced with this tool from other
- logs, the <c>file</c> option is used in <c>tracer/2</c>. The
- logs will therefore be fetched to a directory named
+ logs, option <c>file</c> is used in
+ <seealso marker="ttb#tracer/2"><c>tracer/2</c></seealso>. The
+ logs are therefore fetched to a directory named
<c>ttb_upload_debug_log-YYYYMMDD-HHMMSS</c>
</p>
- <p>By using the <c>handler</c> option when starting the tracer,
+ <p>By using option <c>handler</c> when starting the tracer,
the information about how to format the file is stored in the
trace information file (<c>.ti</c>). This is not necessary, as
- it might be given at the time of formatting instead. It can
- however be useful if you e.g. want to automatically format your
- trace logs by using the <c>format</c> option in
- <c>ttb:stop/1</c>. It also means that you don't need any
- knowledge of the content of a binary log to be able to format it
- the way it was intended. If the <c>handler</c> option is given
- both when starting the tracer and when formatting, the one given
- when formatting is used.
+ it can be specified when formatting instead. However, It can
+ be useful if you, for example, want to format trace logs automatically
+ using option <c>format</c> in <c>ttb:stop/1</c>. Also, you do not need
+ any knowledge of the content of a binary log to format it the way it
+ is intended. If option <c>handler</c> is specified both when starting
+ the tracer and when formatting, the one specified when formatting is used.
</p>
- <p>The <c>call</c> trace flag is set on all processes. This
- means that any function activated with the <c>trc/1</c> command
- will be traced on all existing and new processes.
+ <p>Trace flag <c>call</c> is set on all processes. This
+ means that any function activated with command <c>trc/1</c>
+ is traced on all existing and new processes.
</p>
</section>
</section>
<section>
- <title>Running the Trace Tool Builder against a remote node</title>
+ <title>Running Trace Tool Builder against Remote Node</title>
<p>The Observer application might not always be available on the
- node that shall be traced (in the following called the "traced
- node"). It is still possible to run the Trace Tool Builder from
+ node to be traced (in the following called the "traced
+ node"). However, Trace Tool Builder can still be run from
another node (in the following called the "trace control node") as
- long as
+ long as the following is fulfilled:
</p>
<list type="bulleted">
<item>The Observer application is available on the trace control node.</item>
- <item>The Runtime Tools application is available on both the
+ <item>The Runtime_Tools application is available on both the
trace control node and the traced node.</item>
</list>
- <p>If the Trace Tool Builder shall be used against a remote node,
+ <p>If Trace Tool Builder is to be used against a remote node,
it is highly recommended to start the trace control node as
<em>hidden</em>. This way it can connect to the traced node
- without the traced node "seeing" it, i.e. if the <c>nodes()</c>
- BIF is called on the traced node, the trace control node will not
- show. To start a hidden node, add the <c>-hidden</c> option to the
- <c>erl</c> command, e.g.</p>
- <code type="none">
-% erl -sname trace_control -hidden </code>
+ without being "seen" by it, that is, if the <c>nodes()</c>
+ BIF is called on the traced node, the trace control node does not
+ show. To start a hidden node, add option <c>-hidden</c> to the
+ <c>erl</c> command, for example:</p>
+ <pre>
+% <input>erl -sname trace_control -hidden</input></pre>
<section>
- <title>Diskless node</title>
+ <title>Diskless Node</title>
<p>If the traced node is diskless, <c>ttb</c> must be started from
- a trace control node with disk access, and the <c>file</c> option
- must be given to the <c>tracer/2</c> function with the value
- <c>{local, File}</c>, e.g.</p>
- <code type="none">
-(trace_control@durin)1> ttb:tracer(mynode@diskless,{file,{local,
-{wrap,"mytrace"}}}).
-{ok,[mynode@diskless]} </code>
+ a trace control node with disk access, and option <c>file</c>
+ must be specified to function <c>tracer/2</c> with value
+ <c>{local, File}</c>, for example:</p>
+ <pre>
+(trace_control@durin)1> <input>ttb:tracer(mynode@diskless,
+ {file,{local,{wrap,"mytrace"}}}).</input>
+{ok,[mynode@diskless]}</pre>
</section>
</section>
<section>
- <title>Additional tracing options</title>
- <p>When setting up a trace, several features may be turned on:</p>
+ <title>More Tracing Options</title>
+ <p>When setting up a trace, the following features can also be activated:</p>
<list type="bulleted">
- <item>time-constrained tracing,</item>
- <item>overload protection,</item>
- <item>autoresuming.</item>
+ <item>Time-constrained tracing</item>
+ <item>Overload protection</item>
+ <item>Autoresume</item>
+ <item><c>dbg</c> mode</item>
</list>
<section>
- <title>Time-constrained tracing</title>
- <p>Sometimes, it may be helpful to enable trace for a
- given period of time (i.e. to monitor a system for 24 hours
- or half of a second). This may be done by issuing additional
- <c>{timer, TimerSpec}</c> option. If <c>TimerSpec</c> has the
+ <title>Time-Constrained Tracing</title>
+ <p>It can sometimes be helpful to enable trace for a
+ specified period of time (for example, to monitor a system for 24 hours
+ or half a second). This can be done with option
+ <c>{timer, TimerSpec}</c>. If <c>TimerSpec</c> has the
form of <c>MSec</c>, the trace is stopped after <c>MSec</c>
- milliseconds using <c>ttb:stop/0</c>. If any additional options
- are provided (<c>TimerSpec = {MSec, Opts}</c>), <c>ttb:stop/1</c>
- is called instead with <c>Opts</c> as the arguments. The timer
- is started with <c>ttb:p/2</c>, so any trace patterns should
- be set up before. <c>ttb:start_trace/4</c>
- always sets up all pattern before invoking <c>ttb:p/2</c>.
- Note that due to network and processing delays the the period
- of tracing is approximate.
- The example below shows how to set up a trace which will be
- automatically stopped and formatted after 5 seconds
- </p><code>
-(tiger@durin)1>ttb:start_trace([node()],
- [{erlang, now,[]}],
- {all, call},
- [{timer, {5000, format}}]).
-</code>
+ milliseconds using
+ <seealso marker="ttb#stop/0"><c>ttb:stop/0</c></seealso>. If more
+ options are provided (<c>TimerSpec = {MSec, Opts}</c>),
+ <seealso marker="ttb#stop/1"><c>ttb:stop/1</c></seealso>
+ is called instead with <c>Opts</c> as argument.</p>
+ <p>The timer is started with
+ <seealso marker="ttb#p/2"><c>ttb:p/2</c></seealso>, so any trace patterns
+ must be set up in advance.
+ <seealso marker="ttb#start_trace/4"><c>ttb:start_trace/4</c></seealso>
+ always sets up all patterns before invoking <c>ttb:p/2</c>.</p>
+ <p>The following example shows how to set up a trace that is
+ automatically stopped and formatted after 5 seconds:
+ </p><pre>
+(tiger@durin)1> <input>ttb:start_trace([node()],
+ [{erlang, now,[]}],
+ {all, call},
+ [{timer, {5000, format}}]).</input></pre>
+ <note><p>Because of network and processing delays, the period
+ of tracing is approximate.</p></note>
+
</section>
<section>
- <title>Overload protection</title>
- <p>When tracing live systems, special care needs to be always taken
- not to overload a node with too heavy tracing. <c>ttb</c> provides
- the <c>overload</c> option to help to address the problem.</p>
- <p><c>{overload, MSec, Module, Function}</c> instructs the ttb backend
- (called <c>observer_backend</c>, part of the <c>runtime_tools</c>
- application) to perform overload check every <c>MSec</c> milliseconds.
- If the check (namely <c>Module:Function(check)</c>) returns
+ <title>Overload Protection</title>
+ <p>When tracing live systems, always take special care to not
+ overload a node with too heavy tracing. <c>ttb</c> provides
+ option <c>overload</c> to address this problem.</p>
+ <p><c>{overload, MSec, Module, Function}</c> instructs the <c>ttb</c> back end
+ (a part of the <seealso marker="runtime_tools:index">Runtime_Tools</seealso>
+ application) to perform overload check every <c>MSec</c> millisecond.
+ If the check (named <c>Module:Function(check)</c>) returns
<c>true</c>, tracing is disabled on the selected node.</p>
<p>Overload protection activated on one node does not
affect other nodes, where the tracing continues as normal.
- <c>ttb:stop/0/1</c> fetches data from all clients, including everything
- that has been collected before overload protection was activated.
- Note that
- changing trace details (with <c>ttb:p</c> and <c>ttb:tp/tpl...</c>)
- once overload protection gets activated in one of the traced
- nodes is not permitted in order not to allow trace setup
- to be inconsistent between nodes.
- </p>
- <p><c>Module:Function</c> provided with the <c>overload</c> option must
- handle three calls: <c>init</c>, <c>check</c> and <c>stop</c>. <c>init</c>
- and <c>stop</c> allows to perform some setup and teardown required by
- the check. An overload check module could look like this (note that
- <c>check</c> is always called by the same process, so <c>put</c> and
- <c>get</c> are possible).
- </p><code>
+ <c>ttb:stop/0,1</c> fetches data from all clients, including everything
+ collected before the activation of overload protection.</p>
+
+ <note><p>
+ It is not allowed to change trace details
+ (with <c>ttb:p</c> and <c>ttb:tp/tpl...</c>) once overload
+ protection is activated in one of the traced nodes. This is to
+ avoid trace setup being inconsistent between nodes.</p></note>
+
+ <p><c>Module:Function</c> provided with option <c>overload</c> must
+ handle three calls: <c>init</c>, <c>check</c>, and <c>stop</c>. <c>init</c>
+ and <c>stop</c> allow some setup and teardown required by
+ the check. An overload check module can look as follows:
+ </p><code type="none">
-module(overload).
-export([check/1]).
@@ -362,33 +372,37 @@ check(check) ->
end;
check(stop) ->
get(pid) ! stop.</code>
+ <note><p>
+ <c>check</c> is always called by the same process, so <c>put</c> and
+ <c>get</c> are possible.</p></note>
</section>
<section>
<title>Autoresume</title>
- <p>It is possible that a node (probably a buggy one, hence traced)
- crashes. In order to automatically resume tracing on the node
- as soon as it gets back, <c>resume</c> has to be used. When
- it is, the failing node tries to reconnect
- to trace control node as soon as <c>runtime tools</c> is started.
- This implies that <c>runtime_tools</c> must be included in
- other node's startup chain (if it is not, one could still
- resume tracing by starting <c>runtime_tools</c> manually,
- i.e. by an RPC call).</p>
- <p>In order not to loose the data that the failing node stored
- up to the point of crash, the control node will try to fetch
- it before restarting trace. This must happen within the allowed
- time frame or is aborted (default is 10 seconds, can be customized with
- <c>{resume, MSec}</c>). The data fetched this way is then
- merged with all other traces.</p>
- <p>Autostart feature requires additional data to be stored on
+ <p>A node can crash (probably a buggy one, hence traced).
+ Use <c>resume</c> to resume tracing on the node automatically
+ when it gets back. The failing node then tries to reconnect
+ to trace control node when <c>Runtime_Tools</c> is started.
+ This implies that <c>Runtime_Tools</c> must be included in
+ the startup chain of other nodes (if not, you can still
+ resume tracing by starting <c>Runtime_Tools</c> manually,
+ that is, by an RPC call).</p>
+ <p>To not lose the data that the failing node stored
+ up to the point of crash, the control node tries to fetch
+ it before restarting trace. This must occur within the allowed
+ time frame, otherwise it is aborted (default is 10 seconds, but it
+ can be changed with <c>{resume, MSec}</c>). The data fetched
+ this way is then merged with all other traces.</p>
+ <p>The autostart feature requires more data to be stored on
traced nodes. By default, the data is stored automatically
- to the file called "ttb_autostart.bin" in the traced node's cwd.
- Users may decide to change this behaviour (i.e. on diskless
+ to the file named "ttb_autostart.bin" in the currect working directory
+ (cwd) of the traced node.
+ Users can change this behaviour (that is, on diskless
nodes) by specifying their own module to handle autostart data
storage and retrieval (<c>ttb_autostart_module</c>
- environment variable of <c>runtime_tools</c>). Please see the
- ttb's reference manual to see the module's API. This example
- shows the default handler</p>
+ environment variable of <c>runtime_tools</c>). For information
+ about the API, see module
+ <seealso marker="ttb"><c>ttb</c></seealso>.
+ The following example shows the default handler:</p>
<code>
-module(ttb_autostart).
-export([read_config/0,
@@ -407,54 +421,60 @@ read_config() ->
end.
write_config(Data) ->
- file:write_file(?AUTOSTART_FILENAME, term_to_binary(Data)).
- </code>
- <p>Remember that file trace ports buffer the data
+ file:write_file(?AUTOSTART_FILENAME, term_to_binary(Data)).</code>
+
+ <note><p>Remember that file trace ports buffer the data
by default. If the node crashes, trace messages are not
- flushed to the binary log. If the chance of failure is
- high, it might be a good idea to automatically flush
- the buffers every now and then. Passing <c>{flush, MSec}</c>
- as one of <c>ttb:tracer/2</c> option flushes all buffers
- every <c>MSec</c> milliseconds.</p>
+ flushed to the binary log. If the risk of failure is
+ high, it can be a good idea to flush the buffers every
+ now and then automatically. Passing <c>{flush, MSec}</c>
+ as an option of <c>ttb:tracer/2</c> flushes all buffers
+ every <c>MSec</c> millisecond.</p></note>
</section>
<section>
- <title>dbg mode</title>
- <p>The <c>{shell, ShellType}</c> option allows to make <c>ttb</c>
- operation similar to <c>dbg</c>. Using <c>{shell, true}</c>
+ <title>dbg Mode</title>
+ <p>Option <c>{shell, ShellType}</c> allows making <c>ttb</c>
+ operation similar to
+ <seealso marker="runtime_tools:dbg"><c>dbg</c></seealso>.
+ Using <c>{shell, true}</c>
displays all trace messages in the shell before storing them.
<c>{shell, only}</c> additionally disables message storage
- (so that the tool behaves exactly like dbg). This is allowed
- only with ip trace ports (<c>{trace, {local, File}}</c>).
+ (making the tool to behave exactly like <c>dbg</c>). This is
+ allowed only with IP trace ports (<c>{trace, {local, File}}</c>).
</p>
- <p>The command <c>ttb:tracer(dbg)</c> is a shortcut for the pure-dbg
- mode (<c>{shell, only}</c>).</p>
+ <p>Command <c>ttb:tracer(dbg)</c> is a shortcut for the pure
+ <c>dbg</c> mode (<c>{shell, only}</c>).</p>
</section>
</section>
<section>
<marker id="trace_info"></marker>
- <title>Trace Information and the .ti File</title>
- <p>In addition to the trace log file(s), a file with the extension
- <c>.ti</c> is created when the Trace Tool Builder is started. This
- is the trace information file. It is a binary file, and it
+ <title>Trace Information and File .ti</title>
+ <p>In addition to the trace log file(s), a file with extension
+ <c>.ti</c> is created when Trace Tool Builder is started. This
+ is the trace information file. It is a binary file, which
contains the process information, trace flags used, the name of
- the node to which it belongs and all information written with the
- <c>write_trace_info/2</c> function. .ti files are always fetched
- with other logs when the trace is stopped.
+ the node to which it belongs, and all information written with
+ function
+ <seealso marker="ttb#write_trace_info/2"><c>ttb:write_trace_info/2</c></seealso>.
+ <c>.ti</c> files are always fetched with other logs when the trace is stopped.
</p>
<p>Except for the process information, everything in the trace
information file is passed on to the handler function when
- formatting. The <c>TI</c> parameter is a list of
+ formatting. Parameter <c>TI</c> is a list of
<c>{Key,ValueList}</c> tuples. The keys <c>flags</c>,
- <c>handler</c>, <c>file</c> and <c>node</c> are used for
+ <c>handler</c>, <c>file</c>, and <c>node</c> are used for
information written directly by <c>ttb</c>.
</p>
- <p>You can add information to the trace information file by
- calling <c>write_trace_info/2</c>. Note that <c>ValueList</c>
- always will be a list, and if you call <c>write_trace_info/2</c>
- several times with the same <c>Key</c>, the <c>ValueList</c> will
- be extended with a new value each time. Example:
+ <p>Information to the trace information file by
+ can be added by calling
+ <seealso marker="ttb#write_trace_info/2"><c>ttb:write_trace_info/2</c></seealso>.
+ Notice that <c>ValueList</c>
+ always is a list, and if you call <c>write_trace_info/2</c>
+ many times with the same <c>Key</c>, the <c>ValueList</c> is
+ extended with a new value each time.
</p>
+ <p><em>Example:</em></p>
<p><c>ttb:write_trace_info(mykey,1)</c> gives the entry
<c>{mykey,[1]}</c> in <c>TI</c>. Another call,
<c>ttb:write_trace_info(mykey,2)</c>, changes this entry to
@@ -467,15 +487,15 @@ write_config(Data) ->
<p>If you want to limit the size of the trace logs, you can use
wrap logs. This works almost like a circular buffer. You can
specify the maximum number of binary logs and the maximum size of
- each log. <c>ttb</c> will create a new binary log each time a log
- reaches the maximum size. When the the maximum number of logs are
+ each log. <c>ttb</c> then creates a new binary log each time a log
+ reaches the maximum size. When the maximum number of logs are
reached, the oldest log is deleted before a new one is created.
</p>
- <p>Note that the overall size of data generated by ttb may be greater
- than the wrap specification would suggest - if a traced node restarts
- and autoresume is enabled, old wrap log is always stored and
+ <note><p>The overall size of data generated by <c>ttb</c> can be greater
+ than the wrap specification suggests. If a traced node restarts
+ and autoresume is enabled, the old wrap log is always stored and
a new one is created.
- </p>
+ </p></note>
<p>Wrap logs can be formatted one by one or all at once. See
<seealso marker="#format">Formatting</seealso>.
</p>
@@ -485,52 +505,61 @@ write_config(Data) ->
<marker id="format"></marker>
<title>Formatting</title>
<p>Formatting can be done automatically when stopping <c>ttb</c>
- (see <seealso marker="#fetch_format">Automatically collect and format logs from all nodes</seealso>), or explicitly by calling
- the <c>ttb:format/1/2</c> function.
+ (see section
+ <seealso marker="#fetch_format">Automatically Collect and Format Logs from All Nodes</seealso>), or explicitly by calling function
+ <c>ttb:format/1,2</c>.
</p>
<p>Formatting means to read a binary log and present it in a
readable format. You can use the default format handler in
<c>ttb</c> to present each trace message as a line of text, or
write your own handler to make more complex interpretations of the
- trace information. You can even use the Event Tracer <c>et</c> to
- present the trace log graphically (see <seealso marker="#et_viewer">Presenting trace logs with Event Tracer</seealso>).
+ trace information. You can also use application ET to
+ present the trace log graphically (see section
+ <seealso marker="#et_viewer">Presenting Trace Logs with Event Tracer</seealso>).
</p>
- <p>The first argument to <c>ttb:format/1/2</c> specifies which
+ <p>The first argument to <c>ttb:format/1,2</c> specifies which
binary log(s) to format. This is usually the name of a directory
- that ttb created during log fetch. Unless there is the <c>disable_sort</c>
- option provided, the logs from different files are always sorted
- according to timestamp in traces.
+ that <c>ttb</c> created during log fetch. Unless option
+ <c>disable_sort</c> is provided, the logs from different files
+ are always sorted according to time-stamp in traces.
</p>
<p>The second argument to <c>ttb:format/2</c> is a list of
- options. The <c>out</c> option specifies the destination where the
- formatted text shall be written. Default destination is
- <c>standard_io</c>, but a filename can also be given. The
- <c>handler</c> option specifies the format handler to use. If this
- option is not given, the <c>handler</c> option given when starting
- the tracer is used. If the <c>handler</c> option was not given
- when starting the tracer either, a default handler is used, which
- prints each trace message as a line of text. The <c>disable_sort</c>
- option indicates that there logs should not be merged according to
- timestamp, but processed one file after another (this might be
- a bit faster).
+ options as follows:
</p>
- <p>A format handler is a fun taking four arguments. This fun will
- be called for each trace message in the binary log(s). A simple
- example which only prints each trace message could be like this:</p>
+ <taglist>
+ <tag><c>out</c></tag>
+ <item><p>Specifies the destination to write the formatted text.
+ Default destination is <c>standard_io</c>, but a filename can
+ also be specified.</p></item>
+ <tag><c>handler</c></tag>
+ <item><p>Specifies the format handler to use. If this option is
+ not specified, option <c>handler</c> that is specified when starting
+ the tracer is used. If option <c>handler</c> is not specified
+ when starting the tracer either, a default handler is used, which
+ prints each trace message as a text line.</p></item>
+ <tag><c>disable_sort</c></tag>
+ <item><p>Indicates that the logs are not to be merged according to
+ time-stamp, but processed one file after another (this can be
+ a bit faster).</p></item>
+ </taglist>
+ <p>A format handler is a fun taking four arguments. This fun is
+ called for each trace message in the binary log(s). A simple
+ example that only prints each trace message can be as follows:</p>
<code type="none">
fun(Fd, Trace, _TraceInfo, State) ->
io:format(Fd, "Trace: ~p~n", [Trace]),
State
end. </code>
- <p><c>Fd</c> is the file descriptor for the destination file, or
+ <p>Here, <c>Fd</c> is the file descriptor for the destination file, or
the atom <c>standard_io</c>. <c>_TraceInfo</c> contains information
- from the trace information file (see <seealso marker="#trace_info">Trace Information and the .ti File</seealso>). <c>State</c> is a state variable for the format
- handler fun. The initial value of the <c>State</c> variable is
- given with the handler option, e.g.</p>
+ from the trace information file (see section
+ <seealso marker="#trace_info">Trace Information and File .ti</seealso>). <c>State</c> is a state variable for the format
+ handler fun. The initial value of variable <c>State</c> is
+ specified with the handler option, for example:</p>
<code type="none">
ttb:format("tiger@durin-ttb", [{handler, {{Mod,Fun}, initial_state}}])
^^^^^^^^^^^^^ </code>
- <p>Another format handler could be used to calculate time spent by
+ <p>Another format handler can be used to calculate the time spent by
the garbage collector:</p>
<code type="none">
fun(_Fd,{trace_ts,P,gc_start,_Info,StartTs},_TraceInfo,State) ->
@@ -541,111 +570,118 @@ fun(_Fd,{trace_ts,P,gc_start,_Info,StartTs},_TraceInfo,State) ->
io:format("GC in process ~w: ~w milliseconds~n", [P,Time]),
State -- [{P,StartTs}]
end </code>
- <p>A more refined version of this format handler is the function
- <c>handle_gc/4</c> in the module <c>multitrace.erl</c> which can
- be found in the <c>src</c> directory of the Observer application.
+ <p>A more refined version of this format handler is function
+ <c>handle_gc/4</c> in module <c>multitrace.erl</c>
+ included in directory <c>src</c> of the Observer application.
</p>
- <p>The actual trace message is passed as the second argument (<c>Trace</c>).
- The possible values of <c>Trace</c> are:</p>
+ <p>The trace message is passed as the second argument (<c>Trace</c>).
+ The possible values of <c>Trace</c> are the following:</p>
<list type="bulleted">
- <item>all trace messages described in <c>erlang:trace/3</c> documentation,
+ <item>All trace messages described in
+ <seealso marker="erts:erlang#trace/3"><c>erlang:trace/3</c></seealso>
</item>
- <item><c>{drop, N}</c> if ip tracer is used (see <c>dbg:trace_port/2</c>),
+ <item><c>{drop, N}</c> if IP tracer is used (see
+ <seealso marker="runtime_tools:dbg#trace_port/2"><c>dbg:trace_port/2</c></seealso>)
</item>
- <item><c>end_of_trace</c> received once when all trace messages have
- been processed.</item>
+ <item><c>end_of_trace</c> received once when all trace messages are
+ processed</item>
</list>
- <p>By giving the format handler <c>ttb:get_et_handler()</c>, you can have the trace
- log presented graphically with <c>et_viewer</c> in the Event
- Tracer application (see <seealso marker="#et_viewer">Presenting trace logs with Event Tracer</seealso>).
+ <p>By giving the format handler
+ <seealso marker="ttb#get_et_handler/0"><c>ttb:get_et_handler()</c></seealso>,
+ you can have the trace
+ log presented graphically with <c>et_viewer</c> in the ET
+ application (see section
+ <seealso marker="#et_viewer">Presenting Trace Logs with Event Tracer</seealso>).
</p>
- <p>You may always decide not to format the whole trace data contained
- in the fetch directory, but analyze single files instead. In order
- to do so, a single file (or list of files) have to be passed as
- the first argument to <c>format/1/2</c>.</p>
- <p>Wrap logs can be formatted one by one or all in one go. To
- format one of the wrap logs in a set, give the exact name of the
- file. To format the whole set of wrap logs, give the name with '*'
- instead of the wrap count. An example:
+ <p>You can always decide not to format the whole trace data contained
+ in the fetch directory, but analyze single files instead. To do so,
+ a single file (or list of files) must be passed as the first argument
+ to <c>format/1,2</c>.</p>
+ <p>Wrap logs can be formatted one by one or all at once. To
+ format one of the wrap logs in a set, specify the exact file name.
+ To format the whole set of wrap logs, specify the name with <c>*</c>
+ instead of the wrap count.
</p>
+ <p><em>Example:</em></p>
<p>Start tracing:</p>
- <code type="none">
-(tiger@durin)1> ttb:tracer(node(),{file,{wrap,"trace"}}).
+ <pre>
+(tiger@durin)1> <input>ttb:tracer(node(),{file,{wrap,"trace"}}).</input>
{ok,[tiger@durin]}
-(tiger@durin)2> ttb:p(...)
-... </code>
- <p>This will give a set of binary logs, like:</p>
+(tiger@durin)2> <input>ttb:p(...)</input>
+...</pre>
+ <p>This gives a set of binary logs, for example:</p>
<code type="none">
... </code>
<p>Format the whole set of logs:</p>
- <code type="none">
-1> ttb:format("tiger@durin-trace.*.wrp").
+ <pre>
+1> <input>ttb:format("tiger@durin-trace.*.wrp").</input>
....
ok
-2> </code>
+2> </pre>
<p>Format only the first log:</p>
- <code type="none">
-1> ttb:format("[email protected]").
+ <pre>
+1> <input>ttb:format("[email protected]").</input>
....
ok
-2> </code>
+2> </pre>
<p>To merge all wrap logs from two nodes:</p>
- <code type="none">
-1> ttb:format(["tiger@durin-trace.*.wrp","lion@durin-trace.*.wrp"]).
+ <pre>
+1> <input>ttb:format(["tiger@durin-trace.*.wrp","lion@durin-trace.*.wrp"]).</input>
....
ok
-2> </code>
+2> </pre>
<section>
<marker id="et_viewer"></marker>
- <title>Presenting trace logs with Event Tracer</title>
- <p>For detailed information about the Event Tracer, please turn
- to the User's Guide and Reference Manuals for the <c>et</c>
- application.
+ <title>Presenting Trace Logs with Event Tracer</title>
+ <p>For detailed information about the Event Tracer, see the
+ <seealso marker="et:users_guide">ET</seealso> application.
</p>
- <p>By giving the format handler <c>ttb:get_et_handler()</c>, you can have the
- trace log presented graphically with <c>et_viewer</c> in the
- Event Tracer application. <c>ttb</c> provides a few different
- filters which can be selected from the Filter menu in the
- <c>et_viewer</c> window. The filters are names according to the
- type of actors they present (i.e. what each vertical line in the
- sequence diagram represent). Interaction between actors is shown
- as red arrows between two vertical lines, and activities within
- an actor are shown as blue text to the right of the actors line.
+ <p>By giving the format handler
+ <seealso marker="ttb#get_et_handler/0"><c>ttb:get_et_handler()</c></seealso>,
+ you can have the trace log presented graphically with
+ <c>et_viewer</c> in the ET application.
+ <c>ttb</c> provides filters that can be selected from the
+ menu <em>Filter</em> in the <c>et_viewer</c> window. The filters
+ are names according to the type of actors they present
+ (that is, what each vertical line in the sequence diagram represents).
+ Interaction between actors is shown as red arrows between two
+ vertical lines, and activities within an actor are shown as
+ blue text to the right of the actors line.
</p>
- <p>The <c>processes</c> filter is the only filter which will
- show all trace messages from a trace log. Each vertical line in
+ <p>The <c>processes</c> filter is the only filter showing all
+ trace messages from a trace log. Each vertical line in
the sequence diagram represents a process. Erlang messages,
- spawn and link/unlink are typical interactions between
- processes. Function calls, scheduling and garbage collection are
- typical activities within a process. <c>processes</c> is the
- default filter.
+ spawn, and link/unlink are typical interactions between
+ processes. Function calls, scheduling, and garbage collection,
+ are typical activities within a process. <c>processes</c> is
+ the default filter.
</p>
- <p>The rest of the filters will only show function calls and
+ <p>The remaining filters only show function calls and
function returns. All other trace message are discarded. To get
- the most out of these filters, <c>et_viewer</c> needs to known
+ the most out of these filters, <c>et_viewer</c> must know
the caller of each function and the time of return. This can be
- obtained by using both the <c>call</c> and <c>return_to</c>
- flags when tracing. Note that the <c>return_to</c> flag only
- works with local call trace, i.e. when trace patterns are set
+ obtained using both the <c>call</c> and <c>return_to</c>
+ flags when tracing. Notice that flag <c>return_to</c> only
+ works with local call trace, that is, when trace patterns are set
with <c>ttb:tpl</c>.
</p>
- <p>The same result can be obtained by using the <c>call</c> flag
- only and setting a match specification like this on local or
- global function calls:</p>
- <code type="none">
-1> dbg:fun2ms(fun(_) -> return_trace(),message(caller()) end).
-[{'_',[],[{return_trace},{message,{caller}}]}] </code>
- <p>This should however be done with care, since the
- <c>{return_trace}</c> function in the match specification will
- destroy tail recursiveness.
+ <p>The same result can be obtained by using the flag <c>call</c>
+ only and setting a match specification on local or
+ global function calls as follows:</p>
+ <pre>
+1> <input>dbg:fun2ms(fun(_) -> return_trace(),message(caller()) end).</input>
+[{'_',[],[{return_trace},{message,{caller}}]}]</pre>
+ <p>This must however be done with care, as function
+ <c>{return_trace}</c> in the match specification
+ destroys tail recursiveness.
</p>
<p>The <c>modules</c> filter shows each module as a vertical
line in the sequence diagram. External function calls/returns
- are shown as interactions between modules and internal function
+ are shown as interactions between modules, and internal function
calls/returns are shown as activities within a module.
</p>
<p>The <c>functions</c> filter shows each function as a vertical
@@ -656,9 +692,9 @@ ok
<p>The <c>mods_and_procs</c> and <c>funcs_and_procs</c> filters
are equivalent to the <c>modules</c> and <c>functions</c>
filters respectively, except that each module or function can
- have several vertical lines, one for each process it resides on.
+ have many vertical lines, one for each process it resides on.
</p>
- <p>In the next example, modules <c>foo</c> and <c>bar</c> are used:</p>
+ <p>In the following example, modules <c>foo</c> and <c>bar</c> are used:</p>
<code type="none">
-module(foo).
-export([start/0,go/0]).
@@ -673,8 +709,9 @@ go() ->
go ->
bar:f1(),
go()
- end.
-</code><code type="none">
+ end.</code>
+
+<code type="none">
-module(bar).
-export([f1/0,f3/0]).
f1() ->
@@ -685,57 +722,56 @@ f2() ->
f3() ->
ok.</code>
- <p>Now let's set up the trace.</p>
-<code>
-(tiger@durin)1>%%First we retrieve the Pid to limit traced processes set
-(tiger@durin)1>Pid = foo:start().
-(tiger@durin)2>%%Now we set up tracing
-(tiger@durin)2>ttb:tracer().
-(tiger@durin)3>ttb:p(Pid, [call, return_to, procs, set_on_spawn]).
-(tiger@durin)4>ttb:tpl(bar, []).
-(tiger@durin)5>%%Invoke our test function and see output with et viewer
-(tiger@durin)5>Pid ! go.
-(tiger@durin)6>ttb:stop({format, {handler, ttb:get_et_handler()}}).
-</code>
-
- <p>This should render a result similar to the
- following:
+ <p>Setting up the trace:</p>
+<pre>
+(tiger@durin)1> %%First we retrieve the Pid to limit traced processes set
+(tiger@durin)1> <input>Pid = foo:start().</input>
+(tiger@durin)2> %%Now we set up tracing
+(tiger@durin)2> <input>ttb:tracer().</input>
+(tiger@durin)3> <input>ttb:p(Pid, [call, return_to, procs, set_on_spawn]).</input>
+(tiger@durin)4> <input>ttb:tpl(bar, []).</input>
+(tiger@durin)5> %%Invoke our test function and see output with et viewer
+(tiger@durin)5> <input>Pid ! go.</input>
+(tiger@durin)6> <input>ttb:stop({format, {handler, ttb:get_et_handler()}}).</input></pre>
+
+ <p>This renders a result similar to the following:
</p>
- <p></p>
<image file="et_processes.gif">
<icaption>Filter: "processes"</icaption>
</image>
+ <p></p>
<image file="et_modsprocs.gif">
<icaption>Filter: "mods_and_procs"</icaption>
</image>
- <p>Note, that we can use <c>ttb:start_trace/4</c> function to help
- us here:</p>
-<code>
-(tiger@durin)1>Pid = foo:start().
-(tiger@durin)2>ttb:start_trace([node()],
- [{bar,[]}],
- {Pid, [call, return_to, procs, set_on_spawn]}
- {handler, ttb:get_et_handler()}).
-(tiger@durin)3>Pid ! go.
-(tiger@durin)4>ttb:stop(format).
-</code>
+ <p>Notice that function
+ <seealso marker="ttb#start_trace/4"><c>ttb:start_trace/4</c></seealso>
+ can be used as help as follows:</p>
+<pre>
+(tiger@durin)1> <input>Pid = foo:start().</input>
+(tiger@durin)2> <input>ttb:start_trace([node()],
+ [{bar,[]}],
+ {Pid, [call, return_to, procs, set_on_spawn]}
+ {handler, ttb:get_et_handler()}).</input>
+(tiger@durin)3> <input>Pid ! go.</input>
+(tiger@durin)4> <input>ttb:stop(format).</input></pre>
</section>
</section>
<section>
<marker id="fetch_format"></marker>
- <title>Automatically collect and format logs from all nodes</title>
- <p>By default <c>ttb:stop/1</c> fetches trace logs and
- trace information files from all nodes. The logs are stored in a
- new directory named <c>ttb_upload-Filename-Timestamp</c> under the working
- directory of the trace control node. Fetching may be disabled by
- providing the <c>nofetch</c> option to <c>ttb:stop/1</c>. User can
- specify a fetch directory of his choice passing the
- <c>{fetch_dir, Dir}</c> option.
+ <title>Automatically Collect and Format Logs from All Nodes</title>
+ <p>By default,
+
+ <seealso marker="ttb#stop/1"><c>ttb:stop/1</c></seealso> fetches trace logs
+ and trace information files from all nodes. The logs are stored in a
+ new directory named <c>ttb_upload-Filename-Timestamp</c> under the
+ working directory of the trace control node. Fetching can be disabled
+ by providing option <c>nofetch</c> to <c>ttb:stop/1</c>. The user can
+ specify a fetch directory by passing option <c>{fetch_dir, Dir}</c>.
</p>
- <p>If the option <c>format</c> is given to <c>ttb:stop/1</c>, the
+ <p>If option <c>format</c> is specified to <c>ttb:stop/1</c>, the
trace logs are automatically formatted after tracing is
stopped.
</p>
@@ -743,116 +779,122 @@ f3() ->
<section>
<title>History and Configuration Files</title>
- <p>For the tracing functionality, <c>dbg</c> could be used instead
- of the <c>ttb</c> for setting trace flags on processes and trace
- patterns for call trace, i.e. the functions <c>p</c>, <c>tp</c>,
- <c>tpl</c>, <c>ctp</c>, <c>ctpl</c> and <c>ctpg</c>. There are only
- two things added by <c>ttb</c> for these functions:</p>
+ <p>For the tracing functionality,
+ <seealso marker="runtime_tools:dbg"><c>dbg</c></seealso>
+ can be used instead
+ of <c>ttb</c> for setting trace flags on processes and trace
+ patterns for call trace, that is, the functions
+ <c>p</c>, <c>tp</c>, <c>tpl</c>, <c>ctp</c>, <c>ctpl</c>, and <c>ctpg</c>. Only the
+ following two things are added by <c>ttb</c> for these functions:</p>
<list type="bulleted">
- <item>all calls are stored in the history buffer and can be
+ <item>All calls are stored in the history buffer and can be
recalled and stored in a configuration file. This makes it
- easy to setup the same trace environment e.g. if you want to
- compare two test runs. It also reduces the amount of
- typing when using <c>ttb</c> from the erlang shell;</item>
- <item>shortcuts are provided for the most common match
- specifications (in order not to force the user to use
- <c>dbg:fun2ms</c> continually).</item>
+ easy to set up the same trace environment, for example, if you
+ want to compare two test runs. It also reduces the amount of
+ typing when using <c>ttb</c> from the Erlang shell.</item>
+ <item>Shortcuts are provided for the most common match
+ specifications (to not force you to use
+ <seealso marker="runtime_tools:dbg#fun2ms/1"><c>dbg:fun2ms</c></seealso>
+ continually).</item>
</list>
- <p>Use <c>list_history/0</c> to see the content of the history
- buffer, and <c>run_history/1</c> to re-execute one of the entries.
+ <p>Use
+ <seealso marker="ttb#list_history/0"><c>ttb:list_history/0</c></seealso>
+ to see the content of the history buffer and
+ <seealso marker="ttb#run_history/1"><c>ttb:run_history/1</c></seealso>
+ to re-execute one of the entries.
</p>
<p>The main purpose of the history buffer is the possibility to
create configuration files. Any function stored in the history
buffer can be written to a configuration file and used for
- creating a specific configuration at any time with one single
+ creating a specific configuration at any time with a single
function call.
</p>
<p>A configuration file is created or extended with
- <c>write_config/2/3</c>. Configuration files are binary files
+ <seealso marker="ttb#write_config/2"><c>ttb:write_config/2,3</c></seealso>.
+ Configuration files are binary files
and can therefore only be read and written with functions provided
by <c>ttb</c>.
</p>
- <p>You can write the complete content of the history buffer to a
- config file by calling
- <c>ttb:write_config(ConfigFile,all)</c>. And you can write
- selected entries from the history by calling
+ <p>The complete content of the history buffer can be written to a
+ configuration file by calling
+ <c>ttb:write_config(ConfigFile,all)</c>. Selected entries from
+ the history can be written by calling
<c>ttb:write_config(ConfigFile,NumList)</c>, where
<c>NumList</c> is a list of integers pointing out the history
entries to write. Moreover, the history buffer is always dumped
- to <c>ttb_last_config</c> when <c>ttb:stop/0/1</c> is called.
+ to <c>ttb_last_config</c> when <c>ttb:stop/0,1</c> is called.
</p>
- <p>User defined entries can also be written to a config file by
- calling the function
- <c>ttb:write_config(ConfigFile,ConfigList)</c> where
+ <p>User-defined entries can also be written to a configuration file
+ by calling function
+ <c>ttb:write_config(ConfigFile,ConfigList)</c>, where
<c>ConfigList</c> is a list of <c>{Module,Function,Args}</c>.
</p>
<p>Any existing file <c>ConfigFile</c> is deleted and a new file
- is created when <c>write_config/2</c> is called. The option
- <c>append</c> can be used if you wish to add something at the end
- of an existing config file, e.g.
+ is created when <c>write_config/2</c> is called. Option
+ <c>append</c> can be used to add something at the end
+ of an existing configuration file, for example,
<c>ttb:write_config(ConfigFile,What,[append])</c>.
</p>
- <section>
- <title>Example: History and configuration files</title>
- <p>See the content of the history buffer</p>
- <code type="none"><![CDATA[
-(tiger@durin)191> ttb:tracer().
+ <p><em>Example:</em></p>
+ <p>See the content of the history buffer:</p>
+ <pre>
+(tiger@durin)191> <input>ttb:tracer().</input>
{ok,[tiger@durin]}
-(tiger@durin)192> ttb:p(self(),[garbage_collection,call]).
-{ok,{[<0.1244.0>],[garbage_collection,call]}}
-(tiger@durin)193> ttb:tp(ets,new,2,[]).
+(tiger@durin)192> <input>ttb:p(self(),[garbage_collection,call]).</input>
+{ok,{[&lt;0.1244.0>],[garbage_collection,call]}}
+(tiger@durin)193> <input>ttb:tp(ets,new,2,[]).</input>
{ok,[{matched,1}]}
-(tiger@durin)194> ttb:list_history().
+(tiger@durin)194> <input>ttb:list_history().</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
- {3,{ttb,tp,[ets,new,2,[]]}}] ]]></code>
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
+ {3,{ttb,tp,[ets,new,2,[]]}}]</pre>
<p>Execute an entry from the history buffer:</p>
- <code type="none"><![CDATA[
-(tiger@durin)195> ttb:ctp(ets,new,2).
+ <pre>
+(tiger@durin)195> <input>ttb:ctp(ets,new,2).</input>
{ok,[{matched,1}]}
-(tiger@durin)196> ttb:list_history().
+(tiger@durin)196> <input>ttb:list_history().</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
{3,{ttb,tp,[ets,new,2,[]]}},
{4,{ttb,ctp,[ets,new,2]}}]
-(tiger@durin)197> ttb:run_history(3).
+(tiger@durin)197> <input>ttb:run_history(3).</input>
ttb:tp(ets,new,2,[]) ->
-{ok,[{matched,1}]} ]]></code>
+{ok,[{matched,1}]}</pre>
<p>Write the content of the history buffer to a configuration
file:</p>
- <code type="none"><![CDATA[
-(tiger@durin)198> ttb:write_config("myconfig",all).
+ <pre>
+(tiger@durin)198> <input>ttb:write_config("myconfig",all).</input>
ok
-(tiger@durin)199> ttb:list_config("myconfig").
+(tiger@durin)199> <input>ttb:list_config("myconfig").</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
{3,{ttb,tp,[ets,new,2,[]]}},
{4,{ttb,ctp,[ets,new,2]}},
- {5,{ttb,tp,[ets,new,2,[]]}}] ]]></code>
+ {5,{ttb,tp,[ets,new,2,[]]}}]</pre>
<p>Extend an existing configuration:</p>
- <code type="none"><![CDATA[
-(tiger@durin)200> ttb:write_config("myconfig",[{ttb,tp,[ets,delete,1,[]]}],
-[append]).
+ <pre>
+(tiger@durin)200> <input>ttb:write_config("myconfig",[{ttb,tp,[ets,delete,1,[]]}],
+[append]).</input>
ok
-(tiger@durin)201> ttb:list_config("myconfig").
+(tiger@durin)201> <input>ttb:list_config("myconfig").</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
{3,{ttb,tp,[ets,new,2,[]]}},
{4,{ttb,ctp,[ets,new,2]}},
{5,{ttb,tp,[ets,new,2,[]]}},
- {6,{ttb,tp,[ets,delete,1,[]]}}] ]]></code>
+ {6,{ttb,tp,[ets,delete,1,[]]}}]</pre>
<p>Go back to a previous configuration after stopping Trace Tool
Builder:</p>
- <code type="none"><![CDATA[
-(tiger@durin)202> ttb:stop().
+ <pre>
+(tiger@durin)202> <input>ttb:stop().</input>
ok
-(tiger@durin)203> ttb:run_config("myconfig").
+(tiger@durin)203> <input>ttb:run_config("myconfig").</input>
ttb:tracer(tiger@durin,[]) ->
{ok,[tiger@durin]}
-ttb:p(<0.1244.0>,[garbage_collection,call]) ->
-{ok,{[<0.1244.0>],[garbage_collection,call]}}
+ttb:p(&lt;0.1244.0>,[garbage_collection,call]) ->
+{ok,{[&lt;0.1244.0>],[garbage_collection,call]}}
ttb:tp(ets,new,2,[]) ->
{ok,[{matched,1}]}
@@ -866,133 +908,135 @@ ttb:tp(ets,new,2,[]) ->
ttb:tp(ets,delete,1,[]) ->
{ok,[{matched,1}]}
-ok ]]></code>
+ok</pre>
<p>Write selected entries from the history buffer to a
configuration file:</p>
- <code type="none"><![CDATA[
-(tiger@durin)204> ttb:list_history().
+ <pre>
+(tiger@durin)204> <input>ttb:list_history().</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
{3,{ttb,tp,[ets,new,2,[]]}},
{4,{ttb,ctp,[ets,new,2]}},
{5,{ttb,tp,[ets,new,2,[]]}},
{6,{ttb,tp,[ets,delete,1,[]]}}]
-(tiger@durin)205> ttb:write_config("myconfig",[1,2,3,6]).
+(tiger@durin)205> <input>ttb:write_config("myconfig",[1,2,3,6]).</input>
ok
-(tiger@durin)206> ttb:list_config("myconfig").
+(tiger@durin)206> <input>ttb:list_config("myconfig").</input>
[{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[&lt;0.1244.0>,[garbage_collection,call]]}},
{3,{ttb,tp,[ets,new,2,[]]}},
{4,{ttb,tp,[ets,delete,1,[]]}}]
-(tiger@durin)207> ]]></code>
- </section>
+(tiger@durin)207></pre>
</section>
<section>
<title>Sequential Tracing</title>
<p>To learn what sequential tracing is and how it can be used,
- please turn to the reference manual for the
- <em><c>seq_trace</c></em> module in the <em><c>kernel</c></em>
- application.
+ see the Reference Manual for
+ <seealso marker="kernel:seq_trace"><c>seq_trace</c></seealso>.
</p>
- <p>The support for sequential tracing provided by the Trace Tool
- Builder includes </p>
+ <p>The support for sequential tracing provided by Trace Tool
+ Builder includes the following:</p>
<list type="bulleted">
<item>Initiation of the system tracer. This is automatically
- done when a trace port is started with <c>ttb:tracer/0/1/2</c></item>
- <item>Creation of match specifications which activates
- sequential tracing</item>
+ done when a trace port is started with
+ <seealso marker="ttb#tracer/0"><c>ttb:tracer/0,1,2</c></seealso>.</item>
+ <item>Creation of match specifications that activates
+ sequential tracing.</item>
</list>
- <p>Starting sequential tracing requires that a tracer has been
- started with the <c>ttb:tracer/0/1/2</c> function. Sequential
- tracing can then either be started via a trigger function with a
- match specification created with <c>ttb:seq_trigger_ms/0/1</c>,
- or directly by using the <c>seq_trace</c> module in the
- <c>kernel</c> application.
+ <p>Starting sequential tracing requires that a tracer is
+ started with function <c>ttb:tracer/0,1,2</c>. Sequential
+ tracing can then be started in either of the following ways:
</p>
+ <list type="bulleted">
+ <item>Through a trigger function with a match specification
+ created with
+ <seealso marker="ttb#seq_trigger_ms/0"><c>ttb:seq_trigger_ms/0,1</c></seealso>.</item>
+ <item>Directly by using module
+ <seealso marker="kernel:seq_trace"><c>seq_trace</c></seealso>.</item>
+ </list>
- <section>
- <title>Example: Sequential tracing</title>
- <p>In the following example, the function
+ <p><em>Example 1:</em></p>
+ <p>In the following example, function
<c>dbg:get_tracer/0</c> is used as trigger for sequential
tracing:</p>
- <code type="none"><![CDATA[
-(tiger@durin)110> ttb:tracer().
+ <pre>
+(tiger@durin)110> <input>ttb:tracer().</input>
{ok,[tiger@durin]}
-(tiger@durin)111> ttb:p(self(),call).
-{ok,{[<0.158.0>],[call]}}
-(tiger@durin)112> ttb:tp(dbg,get_tracer,0,ttb:seq_trigger_ms(send)).
+(tiger@durin)111> <input>ttb:p(self(),call).</input>
+{ok,{[&lt;0.158.0>],[call]}}
+(tiger@durin)112> <input>ttb:tp(dbg,get_tracer,0,ttb:seq_trigger_ms(send)).</input>
{ok,[{matched,1},{saved,1}]}
-(tiger@durin)113> dbg:get_tracer(), seq_trace:reset_trace().
+(tiger@durin)113> <input>dbg:get_tracer(), seq_trace:reset_trace().</input>
true
-(tiger@durin)114> ttb:stop(format).
-({<0.158.0>,{shell,evaluator,3},tiger@durin}) call dbg:get_tracer()
-SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin})
-{<0.237.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}}
+(tiger@durin)114> <input>ttb:stop(format).</input>
+({&lt;0.158.0>,{shell,evaluator,3},tiger@durin}) call dbg:get_tracer()
+SeqTrace [0]: ({&lt;0.158.0>,{shell,evaluator,3},tiger@durin})
+{&lt;0.237.0>,dbg,tiger@durin} ! {&lt;0.158.0>,{get_tracer,tiger@durin}}
[Serial: {0,1}]
-SeqTrace [0]: ({<0.237.0>,dbg,tiger@durin})
-{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.222>}}
+SeqTrace [0]: ({&lt;0.237.0>,dbg,tiger@durin})
+{&lt;0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port&lt;0.222>}}
[Serial: {1,2}]
ok
-(tiger@durin)116> ]]></code>
- <p>Starting sequential tracing with a trigger is actually more
+(tiger@durin)116></pre>
+ <p><em>Example 2:</em></p>
+ <p>Starting sequential tracing with a trigger is more
useful if the trigger function is not called directly from the
shell, but rather implicitly within a larger system. When
calling a function from the shell, it is simpler to start
- sequential tracing directly, e.g.</p>
- <code type="none"><![CDATA[
-(tiger@durin)116> ttb:tracer().
+ sequential tracing directly, for example, as follows:</p>
+ <pre>
+(tiger@durin)116> <input>ttb:tracer().</input>
{ok,[tiger@durin]}
-(tiger@durin)117> seq_trace:set_token(send,true), dbg:get_tracer(),
-seq_trace:reset_trace().
+(tiger@durin)117> <input>seq_trace:set_token(send,true), dbg:get_tracer(),
+seq_trace:reset_trace().</input>
true
-(tiger@durin)118> ttb:stop(format).
-SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin})
-{<0.246.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}}
+(tiger@durin)118> <input>ttb:stop(format).</input>
+SeqTrace [0]: ({&lt;0.158.0>,{shell,evaluator,3},tiger@durin})
+{&lt;0.246.0>,dbg,tiger@durin} ! {&lt;0.158.0>,{get_tracer,tiger@durin}}
[Serial: {0,1}]
-SeqTrace [0]: ({<0.246.0>,dbg,tiger@durin})
-{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.229>}}
+SeqTrace [0]: ({&lt;0.246.0>,dbg,tiger@durin})
+{&lt;0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port&lt;0.229>}}
[Serial: {1,2}]
ok
-(tiger@durin)120> ]]></code>
- <p>In both examples above, the <c>seq_trace:reset_trace/0</c>
- resets the trace token immediately after the traced function in
- order to avoid lots of trace messages due to the printouts in
- the erlang shell.
+(tiger@durin)120></pre>
+ <p>In both previous examples, <c>seq_trace:reset_trace/0</c>
+ resets the trace token immediately after the traced function
+ to avoid many trace messages because of the printouts in
+ the Erlang shell.
</p>
- <p>All functions in the <c>seq_trace</c> module, except
- <c>set_system_tracer/1</c>, can be used after the trace port has
- been started with <c>ttb:tracer/0/1/2</c>.
+ <p>All functions in module <c>seq_trace</c>, except
+ <c>set_system_tracer/1</c>, can be used after the trace port
+ is started with <c>ttb:tracer/0,1,2</c>.
</p>
- </section>
</section>
<section>
- <title>Example: Multipurpose trace tool</title>
- <p>The module <c>multitrace.erl</c> which can be found in the
- <c>src</c> directory of the Observer application implements a
+ <title>Multipurpose Trace Tool</title>
+ <p>Module <c>multitrace</c> in
+ directory <c>src</c> of the Observer application provides a
small tool with three possible trace settings. The trace messages
- are written to binary files which can be formatted with the
- function <em><c>multitrace:format/1/2</c></em>.
+ are written to binary files, which can be formatted with
+ function <c>multitrace:format/1,2</c>:
</p>
<taglist>
- <tag><em><c>multitrace:debug(What)</c></em></tag>
- <item>Start calltrace on all processes and trace the given
+ <tag><c>multitrace:debug(What)</c></tag>
+ <item><p>Start calltrace on all processes and trace the specified
function(s). The format handler used is
- <c>multitrace:handle_debug/4</c> which prints each call and
- return. <c>What</c> must be an item or a list of items to trace,
- given on the format <c>{Module,Function,Arity}</c>,
- <c>{Module,Function}</c> or just <c>Module</c>.</item>
- <tag><em><c>multitrace:gc(Procs)</c></em></tag>
- <item>Trace garbage collection on the given process(es). The
- format handler used is <c>multitrace:handle_gc/4</c> which
- prints start and stop and the time spent for each GC.</item>
- <tag><em><c>multitrace:schedule(Procs)</c></em></tag>
- <item>Trace in- and out-scheduling on the given process(es). The
- format handler used is <c>multitrace:handle_schedule/4</c> which
- prints each in and out scheduling with process, timestamp and
+ <c>multitrace:handle_debug/4</c> that prints each call and
+ returns. <c>What</c> must be an item or a list of items to trace,
+ specified on the format <c>{Module,Function,Arity}</c>,
+ <c>{Module,Function}</c>, or only <c>Module</c>.</p></item>
+ <tag><c>multitrace:gc(Procs)</c></tag>
+ <item><p>Trace garbage collection on the specified process(es). The
+ format handler used is <c>multitrace:handle_gc/4</c> that
+ prints start, stop, and the time spent for each garbage collection.</p></item>
+ <tag><c>multitrace:schedule(Procs)</c></tag>
+ <item><p>Trace in-scheduling and out-scheduling on the specified process(es).
+ The format handler used is <c>multitrace:handle_schedule/4</c> that
+ prints each in-scheduling and out-scheduling with process, time-stamp, and
current function. It also prints the total time each traced
- process was scheduled in.</item>
+ process was scheduled in.</p></item>
</taglist>
</section>
</chapter>