ttb — observer v2.16

Search documentation of observer

# View Source ttb (observer v2.16)

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(File)

Equivalent to `format(File,[])`.

format(Files, Options)

format(File,Options) -> ok | {error, Reason}

get_et_handler()

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

list_config(ConfigFile)

list_config(ConfigFile) -> Config | {error,Reason}

list_history()

list_history() -> History

p(Item, Flags)

p(Item,Flags) -> Return

run_config(ConfigFile)

run_config(ConfigFile) -> ok | {error,Reason}

run_config(ConfigFile, NumList)

run_config(ConfigFile,NumList) -> ok | {error,Reason}

run_history(Entries)

run_history(N) -> ok | {error, Reason}

seq_trigger_ms()

seq_trigger_ms() -> MatchSpec

seq_trigger_ms(Flags)

seq_trigger_ms(Flags) -> MatchSpec

start_trace(Nodes, Patterns, FlagSpec, TracerOpts)

start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result

stop()

Equivalent to `stop([])`.

stop(Opts)

stop(Opts) -> stopped | {stopped, Dir}

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(A, B, C, D)

tpl(Module [, Function [, Arity]], MatchSpec)

tracer()

tracer() -> Result

tracer/1

tracer(Nodes) -> Result

tracer(Nodes, Opts)

tracer(Nodes,Opts) -> Result

write_config(ConfigFile,Config)

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

write_config(ConfigFile, Config, Opts)

write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}

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

Link to this type

# format_fun()

View Source (not exported)

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

Link to this type

# format_handler()

View Source (not exported)

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

Link to this type

# format_opt()

View Source (not exported)

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

Link to this type

# format_opts()

View Source (not exported)

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

Link to this type

# item()

View Source (not exported)

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

Link to this type

# match_desc()

View Source (not exported)

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

Link to this type

# match_spec()

View Source (not exported)

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

Link to this type

# mfas()

View Source (not exported)

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

Link to this type

# nodes()

View Source (not exported)

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

Link to this type

# stop_opt()

View Source (not exported)

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

Link to this type

# stop_opts()

View Source (not exported)

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

Link to this type

# tp_arity()

View Source (not exported)

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

Link to this type

# tp_function()

View Source (not exported)

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

Link to this type

# tp_module()

View Source (not exported)

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

Link to this type

# trace_flag()

View Source (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

Link to this function

# ctp()

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctp(A)

View Source

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

Link to this function

# ctp(Module, Function)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctp(Module, Function, Arity)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpe(Event)

View Source (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`.

Link to this function

# ctpg()

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpg(A)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpg(Module, Function)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpg(Module, Function, Arity)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpl()

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpl(A)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpl(Module, Function)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# ctpl(Module, Function, Arity)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# format(File)

View Source

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

Equivalent to `format(File,[])`.

Link to this function

# format(Files, Options)

View Source

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

format(File,Options) -> ok | {error, Reason}

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

Link to this function

# get_et_handler()

View Source (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()}])`.

Link to this function

# list_config(ConfigFile)

View Source

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

list_config(ConfigFile) -> Config | {error,Reason}

Lists all entries in the specified configuration file.

Link to this function

# list_history()

View Source

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

list_history() -> 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`.

Link to this function

# p(Item, Flags)

View Source

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

p(Item,Flags) -> Return

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

Link to this function

# run_config(ConfigFile)

View Source

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

run_config(ConfigFile) -> ok | {error,Reason}

Executes all entries in the specified configuration file. Notice that the history of the last trace is always available in file `ttb_last_config`.

Link to this function

# run_config(ConfigFile, NumList)

View Source

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

run_config(ConfigFile,NumList) -> ok | {error,Reason}

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

Link to this function

# run_history(Entries)

View Source

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

run_history(N) -> ok | {error, Reason}

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

Link to this function

# seq_trigger_ms()

View Source

    -spec seq_trigger_ms() -> match_spec().

seq_trigger_ms() -> MatchSpec

Equivalent to `seq_trigger_ms(all)`.

Link to this function

# seq_trigger_ms(Flags)

View Source

    -spec seq_trigger_ms(Flags) -> match_spec()
                            when Flags :: all | SeqTraceFlag | [SeqTraceFlag], SeqTraceFlag :: atom().

seq_trigger_ms(Flags) -> MatchSpec

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.

Link to this function

# start_trace(Nodes, Patterns, FlagSpec, TracerOpts)

View Source (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()}]}.

start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result

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

Link to this function

# stop()

View Source

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

Equivalent to `stop([])`.

Link to this function

# stop(Opts)

View Source

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

stop(Opts) -> stopped | {stopped, Dir}

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

Link to this function

# tp(A, B)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# tp(A, B, C)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# tp(A, B, C, D)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# tpe(Event, MatchSpec)

View Source (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`.

Link to this function

# tpl(A, B)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# tpl(A, B, C)

View Source

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

Equivalent to `tpl/4`.

Link to this function

# tpl(A, B, C, D)

View Source

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

tpl(Module [, Function [, Arity]], MatchSpec)

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"`)

Link to this function

# tracer()

View Source

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

tracer() -> Result

Equivalent to `tracer(node())`.

Link to this function

# tracer/1

View Source

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

tracer(Nodes) -> Result

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,[])`.

Link to this function

# tracer(Nodes, Opts)

View Source

    -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 :: integer(),
                        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()}.

tracer(Nodes,Opts) -> Result

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

Link to this function

# write_config(ConfigFile,Config)

View Source

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

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

Link to this function

# write_config(ConfigFile, Config, Opts)

View Source

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

write_config(ConfigFile,Config,Opts) -> ok | {error,Reason}

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.

Link to this function

# write_trace_info(Key, Info)

View Source

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