<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html 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 -- ttb</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><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">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/observer-1.2.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Observer</strong><br><strong>Reference Manual</strong><br><small>Version 1.2</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p>
<ul class="flipMenu">
<li title="observer (App)"><a href="observer_app.html">observer (App)
</a></li>
<li id="no" title="observer " expanded="false">observer<ul>
<li><a href="observer.html">
Top of manual page
</a></li>
<li title="start-0"><a href="observer.html#start-0">start/0</a></li>
</ul>
</li>
<li id="loadscrollpos" title="ttb " expanded="true">ttb<ul>
<li><a href="ttb.html">
Top of manual page
</a></li>
<li title="start_trace-4"><a href="ttb.html#start_trace-4">start_trace/4</a></li>
<li title="tracer-0"><a href="ttb.html#tracer-0">tracer/0</a></li>
<li title="tracer-1"><a href="ttb.html#tracer-1">tracer/1</a></li>
<li title="tracer-1"><a href="ttb.html#tracer-1">tracer/1</a></li>
<li title="tracer-2"><a href="ttb.html#tracer-2">tracer/2</a></li>
<li title="p-2"><a href="ttb.html#p-2">p/2</a></li>
<li title="-0"><a href="ttb.html#-0">/0</a></li>
<li title="list_history-0"><a href="ttb.html#list_history-0">list_history/0</a></li>
<li title="run_history-1"><a href="ttb.html#run_history-1">run_history/1</a></li>
<li title="write_config-2"><a href="ttb.html#write_config-2">write_config/2</a></li>
<li title="write_config-3"><a href="ttb.html#write_config-3">write_config/3</a></li>
<li title="run_config-1"><a href="ttb.html#run_config-1">run_config/1</a></li>
<li title="run_config-2"><a href="ttb.html#run_config-2">run_config/2</a></li>
<li title="list_config-1"><a href="ttb.html#list_config-1">list_config/1</a></li>
<li title="write_trace_info-2"><a href="ttb.html#write_trace_info-2">write_trace_info/2</a></li>
<li title="seq_trigger_ms-0"><a href="ttb.html#seq_trigger_ms-0">seq_trigger_ms/0</a></li>
<li title="seq_trigger_ms-1"><a href="ttb.html#seq_trigger_ms-1">seq_trigger_ms/1</a></li>
<li title="stop-0"><a href="ttb.html#stop-0">stop/0</a></li>
<li title="stop-1"><a href="ttb.html#stop-1">stop/1</a></li>
<li title="get_et_handler-0"><a href="ttb.html#get_et_handler-0">get_et_handler/0</a></li>
<li title="format-1"><a href="ttb.html#format-1">format/1</a></li>
<li title="format-2"><a href="ttb.html#format-2">format/2</a></li>
</ul>
</li>
<li id="no" title="etop " expanded="false">etop<ul>
<li><a href="etop.html">
Top of manual page
</a></li>
<li title="start-0"><a href="etop.html#start-0">start/0</a></li>
<li title="start-1"><a href="etop.html#start-1">start/1</a></li>
<li title="help-0"><a href="etop.html#help-0">help/0</a></li>
<li title="config-2"><a href="etop.html#config-2">config/2</a></li>
<li title="dump-1"><a href="etop.html#dump-1">dump/1</a></li>
<li title="stop-0"><a href="etop.html#stop-0">stop/0</a></li>
</ul>
</li>
<li id="no" title="crashdump_viewer " expanded="false">crashdump_viewer<ul>
<li><a href="crashdump_viewer.html">
Top of manual page
</a></li>
<li title="start-0"><a href="crashdump_viewer.html#start-0">start/0</a></li>
<li title="stop-0"><a href="crashdump_viewer.html#stop-0">stop/0</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>ttb</h1></center>
<h3>MODULE</h3>
<div class="REFBODY">ttb</div>
<h3>MODULE SUMMARY</h3>
<div class="REFBODY">A base for building trace tools for distributed systems.</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>The Trace Tool Builder <span class="code">ttb</span> is a base for building trace
tools for distributed systems.
</p>
<p>When using <span class="code">ttb</span>, <span class="code">dbg</span> shall not be used in parallel.</p>
</p></div>
<h3>EXPORTS</h3>
<p><a name="start_trace-4"><span class="bold_code">start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Result = see p/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Nodes = see tracer/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Patterns = [tuple()]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">FlagSpec = {Procs, Flags}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Proc = see p/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Flags = see p/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opts = see tracer/2</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>This function is a shortcut allowing to start a trace with one command. Each
tuple in <span class="code">Patterns</span> is converted to list which is in turn passed to
<span class="code">ttb:tpl</span>.
The call:<div class="example"><pre>
ttb:start_trace([Node, OtherNode],
[{mod, foo, []}, {mod, bar, 2}],
{all, call},
[{file, File}, {handler,{fun myhandler/4, S}}])</pre></div>
is equivalent to <div class="example"><pre>
ttb:start_trace([Node, OtherNode], [{file, File}, {handler,{fun myhandler/4, S}}]),
ttb:tpl(mod, foo, []),
ttb:tpl(mod, bar, 2, []),
ttb:p(all, call)</pre></div>
</p>
</p></div>
<p><a name="tracer-0"><span class="bold_code">tracer() -> Result</span></a><br></p>
<div class="REFBODY"><p>
<p>This is equivalent to <span class="code">tracer(node())</span>.</p>
</p></div>
<p><a name="tracer-1"><span class="bold_code">tracer(Shortcut) -> Result</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Shortcut = shell | dbg</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p><span class="code">shell</span> is equivalent to <span class="code">tracer(node(),[{file, {local, "ttb"}}, shell])</span>.</p>
<p><span class="code">dbg</span> is equivalent to <span class="code">tracer(node(),[{shell, only}])</span>.</p>
</p></div>
<p><a name="tracer-1"><span class="bold_code">tracer(Nodes) -> Result</span></a><br></p>
<div class="REFBODY"><p>
<p>This is equivalent to <span class="code">tracer(Nodes,[])</span>.</p>
</p></div>
<p><a name="tracer-2"><span class="bold_code">tracer(Nodes,Opts) -> Result</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Result = {ok, ActivatedNodes} | {error,Reason}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Nodes = atom() | [atom()] | all | existing | new</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opts = Opt | [Opt]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = {file,Client} | {handler, FormatHandler} | {process_info,PI} |
shell | {shell, ShellSpec} | {timer, TimerSpec} | {overload, {MSec, Module, Function}}
| {flush, MSec} | resume | {resume, FetchTimeout}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">TimerSpec = MSec | {MSec, StopOpts}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">MSec = FetchTimeout = integer()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Module = Function = atom() </span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">StopOpts = see stop/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Client = File | {local, File}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">File = Filename | Wrap</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Filename = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">FormatHandler = See format/2</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">PI = true | false </span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">ShellSpec = true | false | only</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>This function starts a file trace port on all given nodes
and also points the system tracer for sequential tracing to
the same port.
</p>
<p>The given <span class="code">Filename</span> will be prefixed with the node
name. Default <span class="code">Filename</span> is "ttb".
</p>
<p><span class="code">File={wrap,Filename,Size,Count}</span> can be used if
the size of the trace logs must be limited. Default values are
<span class="code">Size=128*1024</span> and <span class="code">Count=8</span>.
</p>
<p>When tracing diskless nodes, <span class="code">ttb</span> must be started
from an external "trace control node" with disk access, and
<span class="code">Client</span> must be <span class="code">{local, File}</span>. All
trace information is then sent to the trace control node where
it is written to file.
</p>
<p>The <span class="code">process_info</span> option indicates if process
information should be collected. If <span class="code">PI = true</span> (which is
default), each process identifier <span class="code">Pid</span> is replaced by a
tuple <span class="code">{Pid,ProcessInfo,Node}</span>, where <span class="code">ProcessInfo</span>
is the process' registered name its globally registered name,
or its initial function. It is possible to turn off this
functionality by setting <span class="code">PI = false</span>.
</p>
<p>The <span class="code">{shell, ShellSpec}</span> option indicates that the trace messages should
be printed on the console as they are received by the tracing
process. This implies <span class="code">{local, File}</span> trace client. If the ShellSpec
is <span class="code">only</span> (instead of <span class="code">true</span>), no trace logs are stored.
</p>
<p>The <span class="code">shell</span> option is a shortcut for <span class="code">{shell, true}</span>.</p>
<p>The <span class="code">timer</span> option indicates that the trace should be
automatically stopped after <span class="code">MSec</span> milliseconds. <span class="code">StopOpts</span>
are passed to <span class="code">ttb:stop/2</span> command if specified (default is <span class="code">[]</span>).
Note that the timing is approximate, as delays related to
network communication are always present. The timer starts after
<span class="code">ttb:p/2</span> is issued, so you can set up your trace patterns before.
</p>
<p>The <span class="code">overload</span> option allows to enable overload
checking on the nodes under trace. <span class="code">Module:Function(check)</span>
is performed each <span class="code">MSec</span> milliseconds. If the check returns
<span class="code">true</span>, the tracing is disabled on a given node.<br>
<span class="code">Module:Function</span> should be able to handle at least three
atoms: <span class="code">init</span>, <span class="code">check</span> and <span class="code">stop</span>. <span class="code">init</span> and
<span class="code">stop</span> give the user a possibility to initialize and clean
up the check environment.<br>
When a node gets overloaded, it is not possible to issue <span class="code">ttb:p</span>
nor any command from the <span class="code">ttb:tp</span> family, as it would lead to
inconsistent tracing state (different trace specifications on
different node).
</p>
<p>The <span class="code">flush</span> option periodically flushes all file trace
port clients (see <span class="code">dbg:flush_trace_port/1</span>). When enabled,
the buffers are freed each <span class="code">MSec</span> milliseconds. This option is
not allowed with <span class="code">{file, {local, File}}</span> tracing.
</p>
<p><span class="code">{resume, FetchTimeout}</span> enables the autoresume feature.
Whenever enabled, remote nodes try to reconnect to the controlling node
in case they were restarted. The feature requires <span class="code">runtime_tools</span>
application to be started (so it has to be present in the <span class="code">.boot</span>
scripts if the traced nodes run with embedded erlang). If this is
not possible, resume may be performed manually by starting
<span class="code">runtime_tools</span> remotely using <span class="code">rpc:call/4</span>.<br>
<span class="code">ttb</span> tries to fetch all logs from a reconnecting node before
reinitializing the trace. This has to finish within FetchTimeout milliseconds
or is aborted<br>
By default, autostart information is stored in a file called
<span class="code">ttb_autostart.bin</span> on each node. If this is not desired
(i.e. on diskless nodes), a custom module to handle autostart
information storage and retrieval can be provided by specifying
<span class="code">ttb_autostart_module</span> environment variable for the <span class="code">runtime_tools</span>
application. The module has to respond to the following API:
<dl>
<dt><strong><span class="code">write_config(Data) -> ok</span></strong></dt>
<dd>Store the provided data for further retrieval. It is
important to realize that the data storage used must not
be affected by the node crash.</dd>
<dt><strong><span class="code">read_config() -> {ok, Data} | {error, Error}</span></strong></dt>
<dd>Retrieve configuration stored with <span class="code">write_config(Data)</span>.</dd>
<dt><strong><span class="code">delete_config() -> ok</span></strong></dt>
<dd>Delete configuration stored with <span class="code">write_config(Data)</span>.
Note that after this call any subsequent calls to <span class="code">read_config</span>
must return <span class="code">{error, Error}</span>.
</dd>
</dl>
</p>
<p>The <span class="code">resume</span> option implies the default <span class="code">FetchTimeout</span>, which is
10 seconds</p>
</p></div>
<p><a name="p-2"><span class="bold_code">p(Procs,Flags) -> Return</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Return = {ok,[{Procs,MatchDesc}]}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Procs = Process | [Process] | all | new | existing</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Process = pid() | atom() | {global,atom()}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Flags = Flag | [Flag]</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>This function sets the given trace flags on the given
processes. The <span class="code">timestamp</span> flag is always turned on.
</p>
<p>Please turn to the Reference manual for module <span class="code">dbg</span>
for details about the possible trace flags. The parameter
<span class="code">MatchDesc</span> is the same as returned from <span class="code">dbg:p/2</span></p>
<p>Processes can be given as registered names, globally
registered names or process identifiers. If a registered name
is given, the flags are set on processes with this name on all
active nodes.</p>
<p>Issuing this command starts the timer for this trace if
<span class="code">timer</span> option was specified with <span class="code">tracer/2</span>.
</p>
</p></div>
<p><a name="-0"><span class="bold_code">tp, tpl, ctp, ctpl, ctpg</span></a><br></p>
<div class="REFBODY"><p>
<p>These functions should be used in combination with the
<span class="code">call</span> trace flag for setting and clearing trace
patterns. When the <span class="code">call</span> trace flag is set on a process,
function calls will be traced on that process if a trace
pattern has been set for the called function. Trace patterns
specifies how to trace a function by using match
specifications. Match specifications are described in the
User's Guide for the erlang runtime system <span class="code">erts</span>.
</p>
<p>These functions are equivalent to the corresponding
functions in <span class="code">dbg</span>, but all calls are stored in the
history. The history buffer makes it easy to create config
files so that the same trace environment can be setup several
times, e.g. if you want to compare two test runs. It also
reduces the amount of typing when using <span class="code">ttb</span> from the
erlang shell.
</p>
<dl>
<dt><strong><span class="code">tp</span></strong></dt>
<dd>Set trace pattern on global function calls</dd>
<dt><strong><span class="code">tpl</span></strong></dt>
<dd>Set trace pattern on local and global function calls</dd>
<dt><strong><span class="code">ctp</span></strong></dt>
<dd>Clear trace pattern on local and global function
calls</dd>
<dt><strong><span class="code">ctpl</span></strong></dt>
<dd>Clear trace pattern on local function calls</dd>
<dt><strong><span class="code">ctpg</span></strong></dt>
<dd>Clear trace pattern on global function calls</dd>
</dl>
<p>With <span class="code">tp</span> and <span class="code">tpl</span> one of match specification shortcuts
may be used (example: <span class="code">ttb:tp(foo_module, caller)</span>). The shortcuts are:
<dl>
<dd>
<span class="code">return</span> - for <span class="code">[{'_',[],[{return_trace}]}]</span>
(report the return value)</dd>
<dd>
<span class="code">caller</span> - for <span class="code">[{'_',[],[{message,{caller}}]}]</span>
(report the calling function)</dd>
<dd>
<span class="code">{codestr, Str}</span> - for <span class="code">dbg:fun2ms/1</span> arguments
passed as strings (example: <span class="code">"fun(_) -> return_trace() end"</span>)
</dd>
</dl>
</p>
</p></div>
<p><a name="list_history-0"><span class="bold_code">list_history() -> History</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">History = [{N,Func,Args}]</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>All calls to <span class="code">ttb</span> is stored in the history. This
function returns the current content of the history. Any entry
can be re-executed with <span class="code">run_history/1</span> or stored in a
config file with <span class="code">write_config/2/3</span>.</p>
</p></div>
<p><a name="run_history-1"><span class="bold_code">run_history(N) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">N = integer() | [integer()]</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Executes the given entry or entries from the history
list. History can be listed with <span class="code">list_history/0</span>.</p>
</p></div>
<p><a name="write_config-2"><span class="bold_code">write_config(ConfigFile,Config)</span></a><br></p>
<div class="REFBODY"><p>
<p>Equivalent to <span class="code">write_config(ConfigFile,Config,[])</span>.</p>
</p></div>
<p><a name="write_config-3"><span class="bold_code">write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">ConfigFile = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Config = all | [integer()] | [{Mod,Func,Args}]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Mod = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Func = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Args = [term()]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opts = Opt | [Opt]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = append</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>This function creates or extends a config file which can be
used for restoring a specific configuration later.
</p>
<p>The content of the config file can either be fetched from
the history or given directly as a list of
<span class="code">{Mod,Func,Args}</span>.
</p>
<p>If the complete history is to be stored in the config file
<span class="code">Config</span> should be <span class="code">all</span>. If only a selected number
of entries from the history should be stored, <span class="code">Config</span>
should be a list of integers pointing out the entries to be
stored.
</p>
<p>If <span class="code">Opts</span> is not given or if it is <span class="code">[]</span>,
<span class="code">ConfigFile</span> is deleted and a new file is created. If
<span class="code">Opts = [append]</span>, <span class="code">ConfigFile</span> will not be deleted.
The new information will be appended at the end of the file.</p>
</p></div>
<p><a name="run_config-1"><span class="bold_code">run_config(ConfigFile) -> ok | {error,Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">ConfigFile = string()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Executes all entries in the given config file. Note that the history
of the last trace is always available in the file named
<span class="code">ttb_last_config</span>.</p>
</p></div>
<p><a name="run_config-2"><span class="bold_code">run_config(ConfigFile,NumList) -> ok | {error,Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">ConfigFile = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">NumList = [integer()]</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Executes selected entries from the given config
file. <span class="code">NumList</span> is a list of integers pointing out the
entries to be executed.
</p>
<p>The content of a config file can be listed with
<span class="code">list_config/1</span>.</p>
<p> Note that the history
of the last trace is always available in the file named
<span class="code">ttb_last_config</span>.</p>
</p></div>
<p><a name="list_config-1"><span class="bold_code">list_config(ConfigFile) -> Config | {error,Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">ConfigFile = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Config = [{N,Func,Args}]</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Lists all entries in the given config file.</p>
</p></div>
<p><a name="write_trace_info-2"><span class="bold_code">write_trace_info(Key,Info) -> ok</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Key = term()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Info = Data | fun() -> Data</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Data = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>The <span class="code">.ti</span> file contains <span class="code">{Key,ValueList}</span>
tuples. This function adds <span class="code">Data</span> to the ValueList
associated with <span class="code">Key</span>. All information written with this
function will be included in the call to the format handler.</p>
</p></div>
<p><a name="seq_trigger_ms-0"><span class="bold_code">seq_trigger_ms() -> MatchSpec</span></a><br></p>
<div class="REFBODY"><p>
<p>Equivalent to <span class="code">seq_trigger_ms(all)</span></p>
</p></div>
<p><a name="seq_trigger_ms-1"><span class="bold_code">seq_trigger_ms(Flags) -> MatchSpec</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">MatchSpec = match_spec()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Flags = all | SeqTraceFlag | [SeqTraceFlag]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">SeqTraceFlag = atom()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>A match specification can turn on or off sequential
tracing. This function returns a match specification which
turns on sequential tracing with the given <span class="code">Flags</span>.
</p>
<p>This match specification can be given as the last argument
to <span class="code">tp</span> or <span class="code">tpl</span>. The activated <span class="code">Item</span> will
then become a <strong>trigger</strong> for sequential tracing. This
means that if the item is called on a process with the
<span class="code">call</span> trace flag set, the process will be "contaminated"
with the seq_trace token.
</p>
<p>If <span class="code">Flags = all</span>, all possible flags are set.
</p>
<p>Please turn to the reference manual for the
<strong><span class="code">seq_trace</span></strong> module in the <strong><span class="code">kernel</span></strong>
application to see the possible values for
<span class="code">SeqTraceFlag</span>. For a description of the match_spec()
syntax, please turn to the <strong>User's guide</strong> for the
runtime system (<strong>erts</strong>). The chapter <strong>Match Specification in Erlang</strong> explains the general match
specification "language".
</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>The <strong>system tracer</strong> for sequential tracing is
automatically initiated by <span class="code">ttb</span> when a trace port is
started with <span class="code">ttb:tracer/0/1/2</span>.</p>
</p></div>
</div>
<p>Example of how to use the <span class="code">seq_trigger_ms/0/1</span> function:</p>
<div class="example"><pre>
(tiger@durin)5> ttb:tracer().
{ok,[tiger@durin]}
(tiger@durin)6> ttb:p(all,call).
{ok,{[all],[call]}}
(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
{ok,[{matched,1},{saved,1}]}
(tiger@durin)8> </pre></div>
<p>Whenever <span class="code">mod:func(...)</span> is called after this, the
seq_trace token will be set on the executing process.</p>
</p></div>
<p><a name="stop-0"><span class="bold_code">stop()</span></a><br></p>
<div class="REFBODY"><p>
<p>Equivalent to <span class="code">stop([])</span>.</p>
</p></div>
<p><a name="stop-1"><span class="bold_code">stop(Opts) -> stopped | {stopped, Dir}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Opts = Opt | [Opt]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = nofetch | {fetch_dir, Dir} | format | {format, FormatOpts} | return_fetch_dir</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">FormatOpts = see format/2</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Stops tracing on all nodes. Logs and
trace information files are sent to the trace control
node and stored in a directory named
<span class="code">ttb_upload_FileName-Timestamp</span>, where <span class="code">Filename</span> is
the one provided with <span class="code">{file, File}</span> during trace setup
and <span class="code">Timestamp</span> is of the
form <span class="code">yyyymmdd-hhmmss</span>. Even logs from nodes on the same
machine as the trace control node are moved to this directory.
The history list is saved to a file named <span class="code">ttb_last_config</span>
for further reference (as it will be not longer accessible
through history and configuration management functions (like
<span class="code">ttb:list_history/0</span>).
</p>
<p>The <span class="code">nofetch</span> option indicates that trace logs shall not be
collected after tracing is stopped.
</p>
<p>The <span class="code">{fetch, Dir}</span> option allows to specify the directory
to fetch the data to. If the directory already exists, an
error is thrown.
</p>
<p>The <span class="code">format</span> option indicates that the trace logs
shall be formatted after tracing is stopped. All logs in the fetch directory will be merged.
You may use <span class="code">{format, FormatOpts}</span> to pass additional
arguments to <span class="code">format/2</span>.</p>
<p>The <span class="code">return_fetch_dir</span> option indicates that the return value
should be <span class="code">{stopped, Dir}</span> and not just <span class="code">stopped</span>.
This implies <span class="code">fetch</span>.
</p>
</p></div>
<p><a name="get_et_handler-0"><span class="bold_code">get_et_handler()</span></a><br></p>
<div class="REFBODY"><p>
<p>The <span class="code">et</span> handler returned by the function may be used with <span class="code">format/2</span>
or <span class="code">tracer/2</span>. Example: <span class="code">ttb:format(Dir, [{handler, ttb:get_et_handler()}])</span>.</p>
</p></div>
<p><a name="format-1"><span class="bold_code">format(File)</span></a><br></p>
<div class="REFBODY"><p>
<p>Same as <span class="code">format(File,[])</span>.</p>
</p></div>
<p><a name="format-2"><span class="bold_code">format(File,Options) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">File = string() | [string()]</span><br>
</div>
<div class="REFBODY">This can be the name of a binary log, a list of such logs or the name of a directory containing one or more binary logs.</div>
<div class="REFTYPES">
<span class="bold_code">Options = Opt | [Opt]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = {out,Out} | {handler,FormatHandler} | disable_sort</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Out = standard_io | string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">FormatHandler = {Function, InitialState}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Function = fun(Fd,Trace,TraceInfo,State) -> State</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Fd = standard_io | FileDescriptor</span><br>
</div>
<div class="REFBODY">This is the file descriptor of the destination file <span class="code">Out</span>
</div>
<div class="REFTYPES">
<span class="bold_code">Trace = tuple()</span><br>
</div>
<div class="REFBODY">This is the trace message. Please turn to the Reference manual for the <span class="code">erlang</span>module for details.</div>
<div class="REFTYPES">
<span class="bold_code">TraceInfo = [{Key,ValueList}]</span><br>
</div>
<div class="REFBODY">This includes the keys <span class="code">flags</span>, <span class="code">client</span> and <span class="code">node</span>, and if <span class="code">handler</span> is given as option to the tracer function, this is also included. In addition all information written with the <span class="code">write_trace_info/2</span>function is included. </div>
</div>
<div class="REFBODY"><p>
<p>Reads the given binary trace log(s). The logs are processed
in the order of their timestamp as long as <span class="code">disable_sort</span>
option is not given.
</p>
<p>If <span class="code">FormatHandler = {Function,InitialState}</span>,
<span class="code">Function</span> will be called for each trace message. If
<span class="code">FormatHandler = get_et_handler()</span>, <span class="code">et_viewer</span> in
the <strong>Event Tracer</strong> application (<span class="code">et</span>) is used for presenting
the trace log graphically. <span class="code">ttb</span> provides a few different
filters which can be selected from the Filter menu in the
<span class="code">et_viewer</span>. If <span class="code">FormatHandler</span> is not given, a
default handler is used which presents each trace message as a
line of text.
</p>
<p>The state returned from each call of <span class="code">Function</span> is passed to the next call,
even if next call is to format a message from another log file.
</p>
<p>If <span class="code">Out</span> is given, <span class="code">FormatHandler</span> gets the
file descriptor to <span class="code">Out</span> as the first parameter.
</p>
<p><span class="code">Out</span> is ignored if <span class="code">et</span> format handler is used.
</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. See examples in the
<span class="code">ttb</span> User's Guide.</p>
</p></div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2002-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1043
