ttb(3erl) Erlang Module Definition ttb(3erl)
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} |
{queue_size, QueueSize}
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
QueueSize = non_neg_integer()
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. De-
fault 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 ex-
ternal "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.
queue_size:
When tracing to shell or {local,File}, an ip trace driver is
used internally. The ip trace driver has a queue of maximum
QueueSize messages waiting to be delivered. If the driver
cannot deliver messages as fast as they are produced, the
queue size might be exceeded and messages are dropped. This
parameter is optional, and is only useful if many {drop,N}
trace messages are received by the trace handler. It has no
meaning if shell or {local,File} is not used. See
dbg:trace_port/2 for more information about the ip trace
driver.
process_info:
Indicates if process information is to be collected. If PI =
true (which is default), each process identifier Pid is re-
placed 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 functional-
ity, set PI = false.
{shell, ShellSpec}:
Indicates that trace messages are to be printed on the con-
sole as they are received by the tracing process. This im-
plies trace client {local, File}. If ShellSpec is only (in-
stead of true), no trace logs are stored.
shell:
Shortcut for {shell, true}.
timer:
Indicates that the trace is to be automatically stopped af-
ter 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 communi-
cation 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 initial-
ize 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 Run-
time_Tools remotely using rpc:call/4.
ttb tries to fetch all logs from a reconnecting node before
reinitializing the trace. This must finish within FetchTime-
out 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 au-
tostart 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 im-
portant 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). No-
tice that after this call any subsequent calls to
read_config must return {error, Error}.
resume implies the default FetchTimeout, which is 10 seconds
p(Item,Flags) -> Return
Types:
Return = {ok,[{Item,MatchDesc}]}
Items = Item | [Item]
Item = pid() | port() | RegName | {global,GlobalRegName} |
all | processes | ports | existing | existing_processes | ex-
isting_ports | new | new_processes | new_ports
RegName = atom()
GlobalRegName = term()
Flags = Flag | [Flag]
Sets the specified trace flags on the specified processes or
ports. Flag timestamp is always turned on.
See the Reference Manual for module dbg for the possible trace
flags. Parameter MatchDesc is the same as returned from dbg:p/2.
Processes can be specified as registered names, globally regis-
tered names, or process identifiers. Ports can be specified as
registered names or port identifiers. If a registered name is
specified, the flags are set on processes/ports 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(Module [, Function [, Arity]], MatchSpec)
tp({Module, Function , Arity}, MatchSpec)
tpl(Module [, Function [, Arity]], MatchSpec)
tpl({Module, Function , Arity}, MatchSpec)
ctp()
ctp(Module [, Function [, Arity]])
ctp({Module, Function, Arity})
ctpl()
ctpl(Module [, Function [, Arity]])
ctpl({Module, Function, Arity})
ctpg()
ctpg(Module [, Function [, Arity]])
ctpg({Module, Function, Arity})
tpe(Event,MatchSpec)
ctpe(Event)
These functions are to be used with trace flag call, send, and
'receive' 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.
The send and 'receive' flags enable tracing of all messages sent
and received by the process/port. Trace patterns set with tpe
may limit traced messages based on the message content, the
sender, and/or the receiver.
Trace patterns specify how to trace a function or a message 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 com-
pare 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.
tpe:
Sets trace patterns on messages.
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.
ctpe:
Clears trace patterns on messages.
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 from a traced function)
* 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 in-
tegers 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 ex-
ecuted.
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 writ-
ten 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 se-
quential 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 se-
quential 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 initi-
ated 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, For-
matOpts} | 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 pro-
vided with {file, File} during trace setup and Timestamp is of
the form yyyymmdd-hhmmss. Even logs from nodes on the same ma-
chine as the trace control node are moved to this directory. The
history list is saved to a file named ttb_last_config for fur-
ther reference (as it is no longer accessible through history
and configuration management functions, like ttb:list_his-
tory/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 an-
other 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 * in-
stead of the wrap count. For examples, see the User's Guide.
Ericsson AB observer 2.9.4 ttb(3erl)