aboutsummaryrefslogtreecommitdiffstats
path: root/lib/observer/doc/src/ttb.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/observer/doc/src/ttb.xml')
-rw-r--r--lib/observer/doc/src/ttb.xml416
1 files changed, 416 insertions, 0 deletions
diff --git a/lib/observer/doc/src/ttb.xml b/lib/observer/doc/src/ttb.xml
new file mode 100644
index 0000000000..fcaa1c2504
--- /dev/null
+++ b/lib/observer/doc/src/ttb.xml
@@ -0,0 +1,416 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2002</year>
+ <year>2007</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>ttb</title>
+ <prepared>Siri hansen</prepared>
+ <responsible></responsible>
+ <docno>1</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2002-02-25</date>
+ <rev>PA1</rev>
+ <file>ttb.sgml</file>
+ </header>
+ <module>ttb</module>
+ <modulesummary>A base for building trace tools for distributed systems.</modulesummary>
+ <description>
+ <p>The Trace Tool Builder <c>ttb</c> is a base for building trace
+ tools for distributed systems.
+ </p>
+ <p>When using <c>ttb</c>, <c>dbg</c> shall not be used in parallel.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>tracer() -> Result</name>
+ <fsummary>This is equivalent to tracer(node()).</fsummary>
+ <desc>
+ <p>This is equivalent to <c>tracer(node())</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>tracer(Nodes) -> Result</name>
+ <fsummary>This is equivalent to tracer(Nodes,[]).</fsummary>
+ <desc>
+ <p>This is equivalent to <c>tracer(Nodes,[])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>tracer(Nodes,Opts) -> Result</name>
+ <fsummary>Start a trace port on each given node.</fsummary>
+ <type>
+ <v>Result = {ok, ActivatedNodes} | {error,Reason}</v>
+ <v>Nodes = atom() | [atom()] | all | existing | new</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {file,Client} | {handler, FormatHandler} | {process_info,PI}</v>
+ <v>Client = File | {local, File}</v>
+ <v>File = Filename | Wrap</v>
+ <v>Filename = string()</v>
+ <v>Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}</v>
+ <v>FormatHandler = See format/2</v>
+ <v>PI = true | false </v>
+ </type>
+ <desc>
+ <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 <c>Filename</c> will be prefixed with the node
+ name. Default <c>Filename</c> is "ttb".
+ </p>
+ <p><c>File={wrap,Filename,Size,Count}</c> can be used if
+ the size of the trace logs must be limited. Default values are
+ <c>Size=128*1024</c> and <c>Count=8</c>.
+ </p>
+ <p>When tracing diskless nodes, <c>ttb</c> must be started
+ from an external "trace control node" with disk access, and
+ <c>Client</c> must be <c>{local, File}</c>. All
+ trace information is then sent to the trace control node where
+ it is written to file.
+ </p>
+ <p>The <c>process_info</c> option indicates if process
+ information should be collected. If <c>PI = true</c> (which is
+ default), each process identifier <c>Pid</c> is replaced by a
+ tuple <c>{Pid,ProcessInfo,Node}</c>, where <c>ProcessInfo</c>
+ is the process' registered name its globally registered name,
+ or its initial function. It is possible to turn off this
+ functionality by setting <c>PI = false</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>p(Procs,Flags) -> Return</name>
+ <fsummary>Sets the given trace flags on the given processes.</fsummary>
+ <type>
+ <v>Return = {ok,[{Procs,MatchDesc}]}</v>
+ <v>Procs = Process | [Process] | all | new | existing</v>
+ <v>Process = pid() | atom() | {global,atom()}</v>
+ <v>Flags = Flag | [Flag]</v>
+ </type>
+ <desc>
+ <p>This function sets the given trace flags on the given
+ processes.
+ </p>
+ <p>Please turn to the Reference manual for module <c>dbg</c>
+ for details about the possible trace flags. The parameter
+ <c>MatchDesc</c> is the same as returned from <c>dbg:p/2</c></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>
+ </desc>
+ </func>
+ <func>
+ <name>tp, tpl, ctp, ctpl, ctpg</name>
+ <fsummary>Set and clear trace patterns.</fsummary>
+ <desc>
+ <p>These functions should be used in combination with the
+ <c>call</c> trace flag for setting and clearing trace
+ patterns. When the <c>call</c> 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 <c>erts</c>.
+ </p>
+ <p>These functions are equivalent to the corresponding
+ functions in <c>dbg</c>, 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 <c>ttb</c> from the
+ erlang shell.
+ </p>
+ <taglist>
+ <tag><c>tp</c></tag>
+ <item>Set trace pattern on global function calls</item>
+ <tag><c>tpl</c></tag>
+ <item>Set trace pattern on local and global function calls</item>
+ <tag><c>ctp</c></tag>
+ <item>Clear trace pattern on local and global function
+ calls</item>
+ <tag><c>ctpl</c></tag>
+ <item>Clear trace pattern on local function calls</item>
+ <tag><c>ctpg</c></tag>
+ <item>Clear trace pattern on global function calls</item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>list_history() -> History</name>
+ <fsummary>Returns all calls stored in history</fsummary>
+ <type>
+ <v>History = [{N,Func,Args}]</v>
+ </type>
+ <desc>
+ <p>All calls to <c>ttb</c> is stored in the history. This
+ function returns the current content of the history. Any entry
+ can be re-executed with <c>run_history/1</c> or stored in a
+ config file with <c>write_config/2/3</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>run_history(N) -> ok | {error, Reason}</name>
+ <fsummary>Executes one entry of the history</fsummary>
+ <type>
+ <v>N = integer() | [integer()]</v>
+ </type>
+ <desc>
+ <p>Executes the given entry or entries from the history
+ list. History can be listed with <c>list_history/0</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_config(ConfigFile,Config)</name>
+ <fsummary>Equivalent to write_config(ConfigFile,Config,[]).</fsummary>
+ <desc>
+ <p>Equivalent to <c>write_config(ConfigFile,Config,[])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_config(ConfigFile,Config,Opt) -> ok | {error,Reason}</name>
+ <fsummary>Creates a config file.</fsummary>
+ <type>
+ <v>ConfigFile = string()</v>
+ <v>Config = all | [integer()] | [{Mod,Func,Args}]</v>
+ <v>Mod = atom()</v>
+ <v>Func = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Opt = [] | [append]</v>
+ </type>
+ <desc>
+ <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
+ <c>{Mod,Func,Args}</c>.
+ </p>
+ <p>If the complete history is to be stored in the config file
+ <c>Config</c> should be <c>all</c>. If only a selected number
+ of entries from the history should be stored, <c>Config</c>
+ should be a list of integers pointing out the entries to be
+ stored.
+ </p>
+ <p>If <c>Opt</c> is not given or if it is <c>[]</c>,
+ <c>ConfigFile</c> is deleted and a new file is created. If
+ <c>Opt = [append]</c>, <c>ConfigFile</c> will not be deleted.
+ The new information will be appended at the end of the file.</p>
+ </desc>
+ </func>
+ <func>
+ <name>run_config(ConfigFile) -> ok | {error,Reason}</name>
+ <fsummary>Executes all entries in a config file.</fsummary>
+ <type>
+ <v>ConfigFile = string()</v>
+ </type>
+ <desc>
+ <p>Executes all entries in the given config file.</p>
+ </desc>
+ </func>
+ <func>
+ <name>run_config(ConfigFile,NumList) -> ok | {error,Reason}</name>
+ <fsummary>Executes selected entries from a config file.</fsummary>
+ <type>
+ <v>ConfigFile = string()</v>
+ <v>NumList = [integer()]</v>
+ </type>
+ <desc>
+ <p>Executes selected entries from the given config
+ file. <c>NumList</c> is a list of integers pointing out the
+ entries to be executed.
+ </p>
+ <p>The content of a config file can be listed with
+ <c>list_config/1</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_config(ConfigFile) -> Config | {error,Reason}</name>
+ <fsummary>Lists all entries in a config file.</fsummary>
+ <type>
+ <v>ConfigFile = string()</v>
+ <v>Config = [{N,Func,Args}]</v>
+ </type>
+ <desc>
+ <p>Lists all entries in the given config file.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_trace_info(Key,Info) -> ok</name>
+ <fsummary>Writes any information to the <c>.ti</c>file.</fsummary>
+ <type>
+ <v>Key = term()</v>
+ <v>Info = Data | fun() -> Data</v>
+ <v>Data = term()</v>
+ </type>
+ <desc>
+ <p>The <c>.ti</c> file contains <c>{Key,ValueList}</c>
+ tuples. This function adds <c>Data</c> to the ValueList
+ associated with <c>Key</c>. All information written with this
+ function will be included in the call to the format handler.</p>
+ </desc>
+ </func>
+ <func>
+ <name>seq_trigger_ms() -> MatchSpec</name>
+ <fsummary>Equivalent to seq_trigger_ms(all)</fsummary>
+ <desc>
+ <p>Equivalent to <c>seq_trigger_ms(all)</c></p>
+ </desc>
+ </func>
+ <func>
+ <name>seq_trigger_ms(Flags) -> MatchSpec</name>
+ <fsummary>Returns a match_spec() which starts sequential tracing</fsummary>
+ <type>
+ <v>MatchSpec = match_spec()</v>
+ <v>Flags = all | SeqTraceFlag | [SeqTraceFlag]</v>
+ <v>SeqTraceFlag = atom()</v>
+ </type>
+ <desc>
+ <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 <c>Flags</c>.
+ </p>
+ <p>This match specification can be given as the last argument
+ to <c>tp</c> or <c>tpl</c>. The activated <c>Item</c> will
+ then become a <em>trigger</em> for sequential tracing. This
+ means that if the item is called on a process with the
+ <c>call</c> trace flag set, the process will be "contaminated"
+ with the seq_trace token.
+ </p>
+ <p>If <c>Flags = all</c>, all possible flags are set.
+ </p>
+ <p>Please turn to the reference manual for the
+ <em><c>seq_trace</c></em> module in the <em><c>kernel</c></em>
+ application to see the possible values for
+ <c>SeqTraceFlag</c>. For a description of the match_spec()
+ syntax, please turn to the <em>User's guide</em> for the
+ runtime system (<em>erts</em>). The chapter <em>Match Specification in Erlang</em> explains the general match
+ specification "language".
+ </p>
+ <note>
+ <p>The <em>system tracer</em> for sequential tracing is
+ automatically initiated by <c>ttb</c> when a trace port is
+ started with <c>ttb:tracer/0/1/2</c>.</p>
+ </note>
+ <p>Example of how to use the <c>seq_trigger_ms/0/1</c> function:</p>
+ <code type="none">
+(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> </code>
+ <p>Whenever <c>mod:func(...)</c> is called after this, the
+ seq_trace token will be set on the executing process.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop()</name>
+ <fsummary>Equivalent to stop([])</fsummary>
+ <desc>
+ <p>Equivalent to <c>stop([])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>stop(Opts) -> stopped</name>
+ <fsummary>Stop tracing and fetch/format logs from all nodes</fsummary>
+ <type>
+ <v>Opts = [Opt]</v>
+ <v>Opt = fetch | format</v>
+ </type>
+ <desc>
+ <p>Stops tracing on all nodes.
+ </p>
+ <p>The <c>fetch</c> option indicates that trace logs shall be
+ collected from all nodes after tracing is stopped. This option
+ is useful if nodes on remote machines are traced. Logs and
+ trace information files are then sent to the trace control
+ node and stored in a directory named
+ <c>ttb_upload-Timestamp</c>, where <c>Timestamp</c> is on the
+ form <c>yyyymmdd-hhmmss</c>. Even logs from nodes on the same
+ machine as the trace control node are moved to this directory.
+ </p>
+ <p>The <c>format</c> option indicates that the trace logs
+ shall be formatted after tracing is stopped. Note that this
+ option also implies the <c>fetch</c> option, i.e. logs are
+ collected in a new directory on the trace control node before
+ formatting. All logs in the directory will be merged.</p>
+ </desc>
+ </func>
+ <func>
+ <name>format(File)</name>
+ <fsummary>Same as <c>format(File,[])</c>.</fsummary>
+ <desc>
+ <p>Same as <c>format(File,[])</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>format(File,Options) -> ok | {error, Reason}</name>
+ <fsummary>Format a binary trace log</fsummary>
+ <type>
+ <v>File = string() | [string()]</v>
+ <d>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.</d>
+ <v>Options = [Opt]</v>
+ <v>Opt = {out,Out} | {handler,FormatHandler}</v>
+ <v>Out = standard_io | string()</v>
+ <v>FormatHandler = {Function, InitialState} | et</v>
+ <v>Function = fun(Fd,Trace,TraceInfo,State) -> State</v>
+ <v>Fd = standard_io | FileDescriptor</v>
+ <d>This is the file descriptor of the destination file <c>Out</c></d>
+ <v>Trace = tuple()</v>
+ <d>This is the trace message. Please turn to the Reference manual for the <c>erlang</c>module for details.</d>
+ <v>TraceInfo = [{Key,ValueList}]</v>
+ <d>This includes the keys <c>flags</c>, <c>client</c>and <c>node</c>, and if <c>handler</c>is given as option to the tracer function, this is also included. In addition all information written with the <c>write_trace_info/2</c>function is included. </d>
+ </type>
+ <desc>
+ <p>Reads the given binary trace log(s). If a directory or a
+ list of logs is given and the <c>timestamp</c> flag was set
+ during tracing, the trace messages from the different logs are
+ merged according to the timestamps.
+ </p>
+ <p>If <c>FormatHandler = {Function,InitialState}</c>,
+ <c>Function</c> will be called for each trace message. If
+ <c>FormatHandler = et</c>, <c>et_viewer</c> in the <em>Event Tracer</em> application (<c>et</c>) is used for presenting the
+ trace log graphically. <c>ttb</c> provides a few different
+ filters which can be selected from the Filter menu in the
+ <c>et_viewer</c>. If <c>FormatHandler</c> is not given, a
+ default handler is used which presents each trace message as a
+ line of text.
+ </p>
+ <p>If <c>Out</c> is given, <c>FormatHandler</c> gets the
+ filedescriptor to <c>Out</c> as the first parameter.
+ </p>
+ <p><c>Out</c> is ignored if <c>FormatHandler = et</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. See examples in the
+ <c>ttb</c> User's Guide.</p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+