A base for building trace tools for distributed systems.
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.
Functions
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).
Equivalent to tracer(node())
.
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}])
.
Equivalent to tracer(Nodes,[])
.
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.
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.
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 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
Return = {ok,[{Item,MatchDesc}]}
Items = Item | [Item]
Item = pid() | port() | RegName | {global,GlobalRegName} | all | processes | ports | existing | existing_processes | existing_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 registered 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
.
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 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.
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}
- fordbg:fun2ms/1
arguments passed as strings (example:"fun(_) -> return_trace() end"
)
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
.
N = integer() | [integer()]
Executes the specified entry or entries from the history
list. To list history, use list_history/0
.
Equivalent to write_config(ConfigFile,Config,[])
.
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.
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
.
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
.
ConfigFile = string()
Config = [{N,Func,Args}]
Lists all entries in the specified configuration file.
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.
Equivalent to seq_trigger_ms(all)
.
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.
Equivalent to stop([])
.
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
.
Returns the et
handler, which can be used with format/2
or tracer/2
.
Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}])
.
Equivalent to format(File,[])
.
File = string() | [string()]
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
Trace = tuple()
TraceInfo = [{Key,ValueList}]
Out
.erlang
.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
.