observer

v2.18.2

crashdump_viewer

A WxWidgets based tool for browsing Erlang crashdumps.

For details about how to get started with the Crashdump Viewer, see the User's Guide.

Summary

Functions

start()

Starts the Crashdump Viewer GUI and opens a file dialog where the crashdump can be selected.

start(File)

Starts the Crashdump Viewer GUI and loads the specified crashdump.

stop()

Terminates the Crashdump Viewer and closes all GUI windows.

Functions

start()

-spec start() -> ok | {error, term()}.

Starts the Crashdump Viewer GUI and opens a file dialog where the crashdump can be selected.

start(File)

(since OTP 17.0)

-spec start(File :: string()) -> ok | {error, term()}.

Starts the Crashdump Viewer GUI and loads the specified crashdump.

stop()

-spec stop() -> ok.

Terminates the Crashdump Viewer and closes all GUI windows.

etop

Erlang Top is a tool for presenting information about Erlang processes similar to the information presented by "top" in UNIX.

Start Erlang Top with the provided scripts etop. This starts a hidden Erlang node that connects to the node to be measured. The measured node is specified with option -node. If the measured node has a different cookie than the default cookie for the user who invokes the script, the cookie must be explicitly specified with option -setcookie.

Under Windows, batch file etop.bat can be used.

When executing the etop script, configuration parameters can be specified as command-line options, for example, etop -node testnode@myhost -setcookie MyCookie. The following configuration parameters exist for the tool:

node - The measured node.

Value: atom/0

Mandatory

setcookie - Cookie to use for the etop node. Must be same as the cookie on the measured node.

Value: atom/0

lines - Number of lines (processes) to display.

Value: integer/0

Default: 10

interval - Time interval (in seconds) between each update of the display.

Value: integer/0

Default: 5

accumulate - If true, the execution time and reductions are accumulated.

Value: boolean/0

Default: false

sort - Identifies what information to sort by.

Value: runtime | reductions | memory | msg_q

Default: runtime (reductions if tracing=off)

tracing - etop uses the Erlang trace facility, and thus no other tracing is possible on the measured node while etop is running, unless this option is set to off. Also helpful if the etop tracing causes too high load on the measured node. With tracing off, runtime is not measured.

Value: on | off

Default: on

For details about Erlang Top, see the User's Guide.

Summary

Functions

config(Key, Value)

Changes the configuration parameters of the tool during runtime. Allowed parameters are lines, interval, accumulate, and sort.

dump(File)

Dumps the current display to a text file.

help()

Displays the help of etop and its options.

start()

Starts etop. Notice that etop is preferably started with the etop script.

start(Options)

Starts etop. To view the possible options, use help/0.

stop()

Terminates etop.

Functions

config(Key, Value)

-spec config(Key, Value) -> ok | {error, Reason}
                when Key :: lines | interval | accumulate | sort, Value :: term(), Reason :: term().

Changes the configuration parameters of the tool during runtime. Allowed parameters are lines, interval, accumulate, and sort.

dump(File)

-spec dump(File) -> ok | {error, Reason} when File :: file:filename_all(), Reason :: term().

Dumps the current display to a text file.

help()

(since OTP R15B01)

-spec help() -> ok.

Displays the help of etop and its options.

start()

(since OTP R15B01)

-spec start() -> ok.

Starts etop. Notice that etop is preferably started with the etop script.

start(Options)

(since OTP R15B01)

-spec start(Options) -> ok when Options :: [{Key, Value}], Key :: atom(), Value :: term().

Starts etop. To view the possible options, use help/0.

stop()

-spec stop() -> stop | not_started.

Terminates etop.

observer

A GUI tool for observing an Erlang system.

Observer is a graphical tool for observing the characteristics of Erlang systems. The tool Observer displays system information, application supervisor trees, process information, ETS tables, Mnesia tables, and contains a front end for Erlang tracing with module ttb.

For details about how to get started, see the User's Guide.

Summary

Functions

start()

Starts the Observer GUI. To stop the tool, close the window or call stop/0.

start(Node)

Starts the Observer GUI and tries to connect it to Node.

start_and_wait()

Starts the Observer GUI and only return when it is either stopped or the window is closed

start_and_wait(Node)

Starts the Observer GUI and only return when it is either stopped or the window is closed, connects it directly to Node like start/1.

stop()

Stops the Observer GUI.

Functions

start()

(since OTP R15B)

-spec start() -> ok | {error, term()}.

Starts the Observer GUI. To stop the tool, close the window or call stop/0.

start(Node)

(since OTP 26.0)

-spec start(Node :: node() | [node()]) -> ok | {error, term()}.

Starts the Observer GUI and tries to connect it to Node.

start_and_wait()

(since OTP 26.0)

-spec start_and_wait() -> ok.

Starts the Observer GUI and only return when it is either stopped or the window is closed

start_and_wait(Node)

(since OTP 26.0)

-spec start_and_wait(Node :: node() | [node()]) -> ok.

Starts the Observer GUI and only return when it is either stopped or the window is closed, connects it directly to Node like start/1.

stop()

(since OTP 26.0)

-spec stop() -> ok.

Stops the Observer GUI.

ttb

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.

Summary

Types

format_fun()

format_handler()

format_opt()

format_opts()

item()

match_desc()

match_spec()

mfas()

nodes()

stop_opt()

stop_opts()

tp_arity()

tp_function()

tp_module()

trace_flag()

Functions

ctp()

Equivalent to tpl/4.

ctp(A)

Equivalent to tpl/4.

ctp(Module, Function)

Equivalent to tpl/4.

ctp(Module, Function, Arity)

Equivalent to tpl/4.

ctpe(Event)

Equivalent to tpl/4.

ctpg()

Equivalent to tpl/4.

ctpg(A)

Equivalent to tpl/4.

ctpg(Module, Function)

Equivalent to tpl/4.

ctpg(Module, Function, Arity)

Equivalent to tpl/4.

ctpl()

Equivalent to tpl/4.

ctpl(A)

Equivalent to tpl/4.

ctpl(Module, Function)

Equivalent to tpl/4.

ctpl(Module, Function, Arity)

Equivalent to tpl/4.

format(Files)

Equivalent to format(Files, []).

format(Files, Options)

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.

get_et_handler()

Returns the et handler, which can be used with format/2 or tracer/2.

list_config(ConfigFile)

Lists all entries in the specified configuration file.

list_history()

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.

p(Item, Flags)

Sets the specified trace flags on the specified processes or ports. Flag timestamp is always turned on.

run_config(ConfigFile)

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)

Executes selected entries from the specified configuration file. NumList is a list of integers pointing out the entries to be executed.

run_history(Entries)

Executes the specified entry or entries from the history list. To list history, use list_history/0.

seq_trigger_ms()

Equivalent to seq_trigger_ms(all).

seq_trigger_ms(Flags)

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.

start_trace(Nodes, Patterns, FlagSpec, TracerOpts)

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.

stop()

Equivalent to stop([]).

stop(Opts)

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).

tp(A, B)

Equivalent to tpl/4.

tp(A, B, C)

Equivalent to tpl/4.

tp(A, B, C, D)

Equivalent to tpl/4.

tpe(Event, MatchSpec)

Equivalent to tpl/4.

tpl(A, B)

Equivalent to tpl/4.

tpl(A, B, C)

Equivalent to tpl/4.

tpl(Module, Function, Arity, MatchSpec)

These functions are to be used with trace flag call, send, and 'receive' for setting and clearing trace patterns.

tracer()

Equivalent to tracer(node()).

tracer(Nodes)

Handy shortcuts for common tracing settings.

tracer(Nodes, Opts)

Starts a file trace port on all specified nodes and points the system tracer for sequential tracing to the same port.

write_config(ConfigFile, Config)

Equivalent to write_config(ConfigFile, Config, []).

write_config(ConfigFile, Config, Opts)

Creates or extends a configuration file, which can be used for restoring a specific configuration later.

write_trace_info(Key, Info)

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.

Types

format_fun()

(not exported)

-type format_fun() ::
          fun((Fd :: standard_io | file:fd(),
               Trace :: tuple(),
               TraceInfo :: [{atom(), list()}],
               State :: term()) ->
                  NewState :: term()).

format_handler()

(not exported)

-type format_handler() :: {format_fun(), InitialState :: term()}.

format_opt()

(not exported)

-type format_opt() :: {out, standard_io | file:filename()} | {handler, format_handler()} | disable_sort.

format_opts()

(not exported)

-type format_opts() :: format_opt() | [format_opt()].

item()

(not exported)

-type item() ::
          pid() |
          port() |
          atom() |
          {global, term()} |
          all | processes | ports | existing | existing_processes | existing_ports | new |
          new_processes | new_ports.

match_desc()

(not exported)

-type match_desc() :: [{matched, node(), integer()} | {matched, node(), 0, term()} | {saved, integer()}].

match_spec()

(not exported)

-type match_spec() :: pos_integer() | x | c | cx | [] | dbg:match_spec().

mfas()

(not exported)

-type mfas() :: {Module :: atom(), Function :: atom(), [term()]}.

nodes()

(not exported)

-type nodes() :: node() | [node()] | all.

stop_opt()

(not exported)

-type stop_opt() ::
          nofetch | {fetch_dir, file:filename()} | format | {format, format_opts()} | return_fetch_dir.

stop_opts()

(not exported)

-type stop_opts() :: stop_opt() | [stop_opt()].

tp_arity()

(not exported)

-type tp_arity() :: arity() | '_'.

tp_function()

(not exported)

-type tp_function() :: atom() | '_'.

tp_module()

(not exported)

-type tp_module() :: module() | '_'.

trace_flag()

(not exported)

-type trace_flag() ::
          s | r | m | c | p | sos | sol | sofs | all | clear | send | 'receive' | procs | ports | call |
          arity | return_to | silent | running | exiting | running_procs | running_ports |
          garbage_collection | timestamp | cpu_timestamp | monotonic_timestamp |
          strict_monotonic_timestamp | set_on_spawn | set_on_first_spawn | set_on_link |
          set_on_first_link |
          {tracer, pid() | port()} |
          {tracer, module(), term()}.

Functions

ctp()

-spec ctp() -> {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctp(A)

-spec ctp(Module | {Module, Function, Arity}) -> {ok, MatchDesc :: match_desc()} | {error, term()}
             when Module :: tp_module(), Function :: tp_function(), Arity :: tp_arity().

Equivalent to tpl/4.

ctp(Module, Function)

-spec ctp(Module :: tp_module(), Function :: tp_function()) ->
             {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctp(Module, Function, Arity)

-spec ctp(Module :: tp_module(), Function :: tp_function(), Arity :: tp_arity()) ->
             {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpe(Event)

(since OTP 19.0)

-spec ctpe(Event) -> {ok, MatchDesc} | {error, term()}
              when
                  Event :: send | 'receive',
                  MatchDesc :: [MatchNum],
                  MatchNum :: {matched, node(), 1} | {matched, node(), 0, RPCError :: term()}.

Equivalent to tpl/4.

ctpg()

-spec ctpg() -> {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpg(A)

-spec ctpg(Module | {Module, Function :: tp_function(), Arity :: tp_arity()}) ->
              {ok, MatchDesc :: term()} | {error, term()}
              when Module :: tp_module().

Equivalent to tpl/4.

ctpg(Module, Function)

-spec ctpg(Module :: tp_module(), Function :: tp_function()) ->
              {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpg(Module, Function, Arity)

-spec ctpg(Module :: tp_module(), Function :: tp_function(), Arity :: tp_arity()) ->
              {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpl()

-spec ctpl() -> {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpl(A)

-spec ctpl(Module | {Module, Function :: tp_function(), Arity :: tp_arity()}) ->
              {ok, MatchDesc :: term()} | {error, term()}
              when Module :: tp_module().

Equivalent to tpl/4.

ctpl(Module, Function)

-spec ctpl(Module :: tp_module(), Function :: tp_function()) ->
              {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

ctpl(Module, Function, Arity)

-spec ctpl(Module :: tp_module(), Function :: tp_function(), Arity :: tp_arity()) ->
              {ok, MatchDesc :: match_desc()} | {error, term()}.

Equivalent to tpl/4.

format(Files)

-spec format(Files) -> ok | {error, term()} when Files :: [file:filename()] | file:filename().

Equivalent to format(Files, []).

format(Files, Options)

-spec format(Files, Options) -> ok | {error, term()}
                when Files :: [file:filename()] | file:filename(), Options :: format_opts().

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.

get_et_handler()

(since OTP R15B)

-spec get_et_handler() -> {Fun, InitState} when Fun :: fun(), InitState :: term().

Returns the et handler, which can be used with format/2 or tracer/2.

Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).

list_config(ConfigFile)

-spec list_config(ConfigFile) -> Result
                     when
                         ConfigFile :: file:filename(),
                         Result :: Config | {error, term()},
                         Config :: [{integer(), mfas()}].

Lists all entries in the specified configuration file.

list_history()

-spec list_history() -> History | {error, term()}
                      when History :: [{N :: integer(), Func :: function(), Args :: integer()}].

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.

p(Item, Flags)

-spec p(Item, Flags) -> Result
           when
               Item :: item(),
               Flags :: trace_flag() | [trace_flag()],
               Result :: {ok, [{item(), match_desc()}]}.

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.

run_config(ConfigFile)

-spec run_config(ConfigFile) -> Result
                    when ConfigFile :: file:filename(), Result :: ok | {error, term()}.

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)

-spec run_config(ConfigFile, NumList) -> Result
                    when
                        ConfigFile :: file:filename(),
                        NumList :: [integer()],
                        Result :: ok | {error, term()}.

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.

run_history(Entries)

-spec run_history(Entries) -> ok | {error, term()}
                     when Entries :: [Entry] | Entry | all | all_silent, Entry :: integer().

Executes the specified entry or entries from the history list. To list history, use list_history/0.

seq_trigger_ms()

-spec seq_trigger_ms() -> match_spec().

Equivalent to seq_trigger_ms(all).

seq_trigger_ms(Flags)

-spec seq_trigger_ms(Flags) -> match_spec()
                        when 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.

start_trace(Nodes, Patterns, FlagSpec, TracerOpts)

(since OTP R15B)

-spec start_trace(Nodes, Patterns, FlagSpec, TracerOpts) -> Result
                     when
                         Nodes :: nodes(),
                         Patterns :: [tuple()],
                         FlagSpec :: {item(), trace_flag() | [trace_flag()]},
                         TracerOpts :: term(),
                         Result :: {ok, [{item(), match_desc()}]}.

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).

stop()

-spec stop() -> stopped | {stopped, Dir :: file:filename()}.

Equivalent to stop([]).

stop(Opts)

-spec stop(Opts :: stop_opts()) -> stopped | {stopped, Dir :: file:filename()}.

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.

tp(A, B)

-spec tp(tp_module(), match_spec()) -> {ok, match_desc()} | {error, term()}.

Equivalent to tpl/4.

tp(A, B, C)

-spec tp(tp_module(), tp_function(), match_spec()) -> {ok, match_desc()} | {error, term()}.

Equivalent to tpl/4.

tp(A, B, C, D)

-spec tp(tp_module(), tp_function(), tp_arity(), match_spec()) -> {ok, match_desc()} | {error, term()}.

Equivalent to tpl/4.

tpe(Event, MatchSpec)

(since OTP 19.0)

-spec tpe(Event, MatchSpec) -> {ok, MatchDesc :: match_desc()} | {error, term()}
             when Event :: send | 'receive', MatchSpec :: match_spec().

Equivalent to tpl/4.

tpl(A, B)

-spec tpl(tp_module(), match_spec()) -> {ok, match_desc()} | {error, term()}.

Equivalent to tpl/4.

tpl(A, B, C)

-spec tpl(tp_module(), tp_function(), match_spec()) -> {ok, match_desc()} | {error, term()}.

Equivalent to tpl/4.

tpl(Module, Function, Arity, MatchSpec)

-spec tpl(tp_module(), tp_function(), tp_arity(), match_spec()) -> {ok, match_desc()} | {error, term()}.

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} - for dbg:fun2ms/1 arguments passed as strings (example: "fun(_) -> return_trace() end")

tracer()

-spec tracer() -> {ok, [node()]} | {error, term()}.

Equivalent to tracer(node()).

tracer(Nodes)

-spec tracer(shell | dbg | nodes()) -> {ok, [node()]} | {error, term()}.

Handy shortcuts for common tracing settings.

shell is equivalent to tracer(node(),[{file, {local, "ttb"}}, shell]).

dbg is equivalent to tracer(node(),[{shell, only}]).

Nodes is equivalent to tracer(Nodes,[]).

tracer(Nodes, Opts)

-spec tracer(Nodes, Opts) -> Result
                when
                    Nodes :: nodes(),
                    Opts :: Opt | [Opt],
                    Opt ::
                        {file, Client} |
                        {handler, format_handler()} |
                        {process_info, boolean()} |
                        shell |
                        {shell, ShellSpec} |
                        {timer, TimerSpec} |
                        {overload_check, {MSec, Module, Function}} |
                        {flush, MSec} |
                        resume |
                        {resume, MSec} |
                        {queue_size, non_neg_integer()},
                    TimerSpec :: MSec | {MSec, stop_opts()},
                    MSec :: timer:time(),
                    Module :: atom(),
                    Function :: atom(),
                    Client :: File | {local, File},
                    File :: file:filename() | Wrap,
                    Wrap ::
                        {wrap, file:filename()} |
                        {wrap, file:filename(), Size :: integer(), Count :: integer()},
                    ShellSpec :: true | false | only,
                    Result :: {ok, [node()]} | {error, term()}.

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/1 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

write_config(ConfigFile, Config)

-spec write_config(ConfigFile, Config) -> Result
                      when
                          ConfigFile :: file:filename(),
                          Config :: all | [integer()] | [mfas()],
                          Result :: ok | {error, term()}.

Equivalent to write_config(ConfigFile, Config, []).

write_config(ConfigFile, Config, Opts)

-spec write_config(ConfigFile, Config, Opts) -> Result
                      when
                          ConfigFile :: file:filename(),
                          Config :: all | [integer()] | [mfas()],
                          Opts :: Opt | [Opt],
                          Opt :: append,
                          Result :: ok | {error, term()}.

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.

write_trace_info(Key, Info)

-spec write_trace_info(Key :: term(), Info) -> ok
                          when Info :: Data :: term() | fun(() -> 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.