Provided by: erlang-manpages_18.3-dfsg-1ubuntu3.1_all 
NAME
ttb - A base for building trace tools for distributed systems.
DESCRIPTION
The Trace Tool Builder, ttb, is a base for building trace tools for distributed systems.
When using ttb, do not use module dbg in application Runtime_Tools in parallel.
EXPORTS
start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result
Types:
Result = see p/2
Nodes = see tracer/2
Patterns = [tuple()]
FlagSpec = {Procs, Flags}
Proc = see p/2
Flags = see p/2
Opts = see tracer/2
This function is a shortcut allowing to start a trace with one command. Each tuple
in Patterns is converted to a list, which in turn is passed to ttb:tpl/2,3,4.
The call:
> ttb:start_trace([Node, OtherNode], [{mod, foo, []}, {mod, bar, 2}], {all, call}, [{file, File}, {handler,{fun myhandler/4, S}}]).
is equivalent to:
> 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).
tracer() -> Result
Equivalent to tracer(node()).
tracer(Shortcut) -> Result
Types:
Shortcut = shell | dbg
Handy shortcuts for common tracing settings.
shell is equivalent to tracer(node(),[{file, {local, "ttb"}}, shell]).
dbg is equivalent to tracer(node(),[{shell, only}]).
tracer(Nodes) -> Result
Equivalent to tracer(Nodes,[]).
tracer(Nodes,Opts) -> Result
Types:
Result = {ok, ActivatedNodes} | {error,Reason}
Nodes = atom() | [atom()] | all | existing | new
Opts = Opt | [Opt]
Opt = {file,Client} | {handler, FormatHandler} | {process_info,PI} | shell |
{shell, ShellSpec} | {timer, TimerSpec} | {overload_check, {MSec, Module,
Function}} | {flush, MSec} | resume | {resume, FetchTimeout}
TimerSpec = MSec | {MSec, StopOpts}
MSec = FetchTimeout = integer()
Module = Function = atom()
StopOpts = see stop/2
Client = File | {local, File}
File = Filename | Wrap
Filename = string()
Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}
FormatHandler = See format/2
PI = true | false
ShellSpec = true | false | only
Starts a file trace port on all specified nodes and points the system tracer for
sequential tracing to the same port.
Options:
Filename:
The specified Filename is prefixed with the node name. Default Filename is ttb.
File={wrap,Filename,Size,Count}:
Can be used if the size of the trace logs must be limited. Default values are
Size=128*1024 and Count=8.
Client:
When tracing diskless nodes, ttb must be started from an external "trace
control node" with disk access, and Client must be {local, File}. All trace
information is then sent to the trace control node where it is written to file.
process_info:
Indicates if process information is to be collected. If PI = true (which is
default), each process identifier Pid is replaced by a tuple
{Pid,ProcessInfo,Node}, where ProcessInfo is the registered process name, its
globally registered name, or its initial function. To turn off this
functionality, set PI = false.
{shell, ShellSpec}:
Indicates that trace messages are to be printed on the console as they are
received by the tracing process. This implies trace client {local, File}. If
ShellSpec is only (instead of true), no trace logs are stored.
shell:
Shortcut for {shell, true}.
timer:
Indicates that the trace is to be automatically stopped after MSec
milliseconds. StopOpts are passed to command ttb:stop/2 if specified (default
is []). Notice that the timing is approximate, as delays related to network
communication are always present. The timer starts after ttb:p/2 is issued, so
you can set up your trace patterns before.
overload_check:
Allows to enable overload checking on the nodes under trace.
Module:Function(check) is performed each MSec millisecond. If the check returns
true, the tracing is disabled on a specified node.
Module:Function must be able to handle at least three atoms: init, check, and
stop. init and stop allows you to initialize and clean up the check
environment.
When a node gets overloaded, it is not possible to issue ttb:p/2 or any command
from the ttb:tp/2,3,4 family, as it would lead to inconsistent tracing state
(different trace specifications on different nodes).
flush:
Periodically flushes all file trace port clients (see dbg:flush_trace_port/1).
When enabled, the buffers are freed each MSec millisecond. This option is not
allowed with {file, {local, File}} tracing.
{resume, FetchTimeout}:
Enables the autoresume feature. When enabled, remote nodes try to reconnect to
the controlling node if they are restarted. The feature requires application
Runtime_Tools to be started (so it has to be present in the .boot scripts if
the traced nodes run with embedded Erlang). If this is not possible, resume can
be performed manually by starting Runtime_Tools remotely using rpc:call/4.
ttb tries to fetch all logs from a reconnecting node before reinitializing the
trace. This must finish within FetchTimeout milliseconds or is aborted.
By default, autostart information is stored in a file named ttb_autostart.bin
on each node. If this is not desired (for example, on diskless nodes), a custom
module handling autostart information storage and retrieval can be provided by
specifying environment variable ttb_autostart_module for the application
Runtime_Tools. The module must respond to the following API:
write_config(Data) -> ok:
Stores the provided data for further retrieval. It is important to realize
that the data storage used must not be affected by the node crash.
read_config() -> {ok, Data} | {error, Error}:
Retrieves configuration stored with write_config(Data).
delete_config() -> ok:
Deletes configuration stored with write_config(Data). Notice that after this
call any subsequent calls to read_config must return {error, Error}.
resume implies the default FetchTimeout, which is 10 seconds
p(Procs,Flags) -> Return
Types:
Return = {ok,[{Procs,MatchDesc}]}
Procs = Process | [Process] | all | new | existing
Process = pid() | atom() | {global,atom()}
Flags = Flag | [Flag]
Sets the specified trace flags on the specified processes. Flag timestamp is always
turned on.
See the Reference Manual for module dbg and the possible trace flags. Parameter
MatchDesc is the same as returned from dbg:p/2.
Processes can be specified as registered names, globally registered names, or
process identifiers. If a registered name is specified, the flags are set on
processes with this name on all active nodes.
Issuing this command starts the timer for this trace if option timer is specified
with tracer/2.
tp, tpl, ctp, ctpl, ctpg
These functions are to be used with trace flag call for setting and clearing trace
patterns. When trace flag call is set on a process, function calls are traced on
that process if a trace pattern is set for the called function. Trace patterns
specify how to trace a function by using match specifications. Match specifications
are described in the ERTS User's Guide.
These functions are equivalent to the corresponding functions in module dbg, but
all calls are stored in the history. The history buffer makes it easy to create
configuration files; the same trace environment can be set up many times, for
example, to compare two test runs. It also reduces the amount of typing when using
ttb from the Erlang shell.
tp:
Sets trace patterns on global function calls.
tpl:
Sets trace patterns on local and global function calls.
ctp:
Clears trace patterns on local and global function calls.
ctpl:
Clears trace patterns on local function calls.
ctpg:
Clears trace patterns on global function calls.
With tp and tpl, one of the match specification shortcuts can be used (for example,
ttb:tp(foo_module, caller)).
The shortcuts are as follows:
* return - for [{'_',[],[{return_trace}]}] (report the return value)
* caller - for [{'_',[],[{message,{caller}}]}] (report the calling function)
* {codestr, Str} - for dbg:fun2ms/1 arguments passed as strings (example: "fun(_)
-> return_trace() end")
list_history() -> History
Types:
History = [{N,Func,Args}]
All calls to ttb is stored in the history. This function returns the current
content of the history. Any entry can be reexecuted with run_history/1 or stored in
a configuration file with write_config/2,3.
run_history(N) -> ok | {error, Reason}
Types:
N = integer() | [integer()]
Executes the specified entry or entries from the history list. To list history, use
list_history/0.
write_config(ConfigFile,Config)
Equivalent to write_config(ConfigFile,Config,[]).
write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}
Types:
ConfigFile = string()
Config = all | [integer()] | [{Mod,Func,Args}]
Mod = atom()
Func = atom()
Args = [term()]
Opts = Opt | [Opt]
Opt = append
Creates or extends a configuration file, which can be used for restoring a specific
configuration later.
The contents of the configuration file can either be fetched from the history or
specified directly as a list of {Mod,Func,Args}.
If the complete history is to be stored in the configuration file, Config must be
all. If only a selected number of entries from the history are to be stored, Config
must be a list of integers pointing out the entries to be stored.
If Opts is not specified or if it is [], ConfigFile is deleted and a new file is
created. If Opts = [append], ConfigFile is not deleted. The new information is
appended at the end of the file.
run_config(ConfigFile) -> ok | {error,Reason}
Types:
ConfigFile = string()
Executes all entries in the specified configuration file. Notice that the history
of the last trace is always available in file ttb_last_config.
run_config(ConfigFile,NumList) -> ok | {error,Reason}
Types:
ConfigFile = string()
NumList = [integer()]
Executes selected entries from the specified configuration file. NumList is a list
of integers pointing out the entries to be executed.
To list the contents of a configuration file, use list_config/1.
Notice that the history of the last trace is always available in file
ttb_last_config.
list_config(ConfigFile) -> Config | {error,Reason}
Types:
ConfigFile = string()
Config = [{N,Func,Args}]
Lists all entries in the specified configuration file.
write_trace_info(Key,Info) -> ok
Types:
Key = term()
Info = Data | fun() -> Data
Data = term()
File .ti contains {Key,ValueList} tuples. This function adds Data to the ValueList
associated with Key. All information written with this function is included in the
call to the format handler.
seq_trigger_ms() -> MatchSpec
Equivalent to seq_trigger_ms(all).
seq_trigger_ms(Flags) -> MatchSpec
Types:
MatchSpec = match_spec()
Flags = all | SeqTraceFlag | [SeqTraceFlag]
SeqTraceFlag = atom()
A match specification can turn on or off sequential tracing. This function returns
a match specification, which turns on sequential tracing with the specified Flags.
This match specification can be specified as the last argument to tp or tpl. The
activated Item then becomes a trigger for sequential tracing. This means that if
the item is called on a process with trace flag call set, the process is
"contaminated" with token seq_trace.
If Flags = all, all possible flags are set.
The possible values for SeqTraceFlag are available in seq_trace.
For a description of the match_spec() syntax, see section Match Specifications in
Erlang in ERTS, which explains the general match specification "language".
Note:
The system tracer for sequential tracing is automatically initiated by ttb when a
trace port is started with ttb:tracer/0,1,2.
An example of how to use function seq_trigger_ms/0,1 follows:
(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>
Whenever mod:func(...) is called after this, token seq_trace is set on the
executing process.
stop()
Equivalent to stop([]).
stop(Opts) -> stopped | {stopped, Dir}
Types:
Opts = Opt | [Opt]
Opt = nofetch | {fetch_dir, Dir} | format | {format, FormatOpts} |
return_fetch_dir
Dir = string()
FormatOpts = see format/2
Stops tracing on all nodes. Logs and trace information files are sent to the trace
control node and stored in a directory named ttb_upload_FileName-Timestamp, where
Filename is the one provided with {file, File} during trace setup and Timestamp is
of the form yyyymmdd-hhmmss. 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
ttb_last_config for further reference (as it is no longer accessible through
history and configuration management functions, like ttb:list_history/0).
Options:
nofetch:
Indicates that trace logs are not to be collected after tracing is stopped.
{fetch, Dir}:
Allows specification of the directory to fetch the data to. If the directory
already exists, an error is thrown.
format:
Indicates the trace logs to be formatted after tracing is stopped. All logs in
the fetch directory are merged.
return_fetch_dir:
Indicates the return value to be {stopped, Dir} and not just stopped. This
implies fetch.
get_et_handler()
Returns the et handler, which can be used with format/2 or tracer/2.
Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).
format(File)
Equivalent to format(File,[]).
format(File,Options) -> ok | {error, Reason}
Types:
File = string() | [string()]
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.
Options = Opt | [Opt]
Opt = {out,Out} | {handler,FormatHandler} | disable_sort
Out = standard_io | string()
FormatHandler = {Function, InitialState}
Function = fun(Fd,Trace,TraceInfo,State) -> State
Fd = standard_io | FileDescriptor
File descriptor of the destination file Out.
Trace = tuple()
The trace message. For details, see the Reference Manual for module erlang.
TraceInfo = [{Key,ValueList}]
Includes the keys flags, client, and node. If handler is specified as option
to the tracer function, this is also included. Also, all information written
with function write_trace_info/2 is included.
Reads the specified binary trace log(s). The logs are processed in the order of
their time stamps as long as option disable_sort is not specified.
If FormatHandler = {Function,InitialState}, Function is called for each trace
message.
If FormatHandler = get_et_handler(), et_viewer in application ET is used for
presenting the trace log graphically. ttb provides a few different filters that can
be selected from menu Filters and scaling in the et_viewer.
If FormatHandler is not specified, a default handler is used presenting each trace
message as a text line.
The state returned from each call of Function is passed to the next call, even if
the next call is to format a message from another log file.
If Out is specified, FormatHandler gets the file descriptor to Out as the first
parameter.
Out is ignored if the et format handler is used.
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 * instead of the wrap count. For examples, see the User's
Guide.