View Source tr (erlang_doctor v0.2.6)
Summary
Types
Initialization options.
none.[].Condition checked before collecting message traces for a process.
all.Predicate returning true for matching traces.
Options for trace ranges.
Trace selector function.
tree or return a list (default) of them.Traceback options.
top_down.shortest.Options for repeated call tree statistics.
Specifies the behaviour for overlapping call trees.
Trace record, storing one collected trace event.
tab/0.Function call tree node.
Functions
tab/0.See also: call_stat/2.
Returns call time statistics for traces selected from tr_source/0.
Looks for DataVal in #tr.data.
tab/0 table to a file.tr_source/0.Loads an ETS trace table from a file, and makes it the current table.
Args in an MFA tuple.Prints sorted call time statistics for the selected traces from tab/0.
Returns a list of traces from tab/0 between the first matched call and the corresponding return.
Returns a list of traces from tr_source/0 between the first matched call and the corresponding return.
tr_source/0 between matched calls and corresponding returns.Selects data from matching traces from tab/0 with ets:fun2ms(F).
Returns sorted call time statistics for the selected traces from tab/0.
Starts tr as a stand-alone gen_server. Intended for interactive use.
Stops tracing, disabling all trace specs.
See also: top_call_trees/1.
Returns statistics of repeated function call trees that took most time.
Starts tracing of the specified functions/modules and/or message events.
Returns traceback of the first matching trace from tr_source/0.
Returns traceback of the first matching trace from tr_source/0.
tab/0.See also: tracebacks/2.
tr_source/0.Types
-type acc_time() :: non_neg_integer().
-type call() :: {call, {module(), atom(), list()}}.
-type call_count() :: non_neg_integer().
-type call_tree_count() :: pos_integer().
-type call_tree_stat_options() :: #{tab => table()}.
-type call_tree_stat_state() :: #{pid_states := map(), tab := ets:tid()}.
-type erlang_trace_flags() :: [call | timestamp | send | 'receive'].
-type index() :: pos_integer().
tr/0 record.
Initialization options.
tab is the ETS table used for storing traces (default: trace). index is the index value of the first inserted trace (default: 1). When size of tab reaches the optional limit, tracing is stopped.
-type limit() :: pos_integer() | infinity.
-type message_event_types() :: send | recv | all | none.
none.
-type mfargs() :: {module(), atom(), list()}.
-type module_spec() :: [module() | mfa()].
[].
-type msg_trigger() :: after_traced_call | always.
Condition checked before collecting message traces for a process.
after_traced_call (default) means that a process needs to call at least one traced function before its message events start being collected. always means that messages for all traced processes are collected.
-type own_time() :: non_neg_integer().
-type pids() :: [pid()] | all.
all.
-type pred() :: fun((tr()) -> boolean()).
Predicate returning true for matching traces.
Options for trace ranges.
Optionallimit is the maximum depth of calls in the returned ranges. All traces (including messages) exceeding that depth are skipped.
-type recipient() :: {pid(), boolean()}.
-type result() :: {return | exception, any()}.
-type selector(Data) :: fun((tr()) -> Data).
Trace selector function.
For selected traces, it returnsData. For other traces, it should fail.
-type state() :: #{tab := table(), index := index(), limit := limit(), trace := none | trace_spec(), tracer_pid := none | pid()}.
-type table() :: atom().
-type tb_acc() :: tb_acc_tree() | tb_acc_list().
-type tb_acc_list() :: [[tr()]].
-type tb_acc_tree() :: [{tr(), tb_acc_tree()}].
-type tb_format() :: tree | list.
tree or return a list (default) of them.
-type tb_options() :: #{tab => tr_source(), output => tb_output(), format => tb_format(), order => tb_order(), limit => limit()}.
Traceback options.
Optionallimit is the maximum number of tracebacks to collect before filtering them according to output.
-type tb_order() :: top_down | bottom_up.
top_down.
-type tb_output() :: shortest | longest | all.
shortest.
-type top_call_trees_options() :: #{max_size => pos_integer(), min_count => call_tree_count(), min_time => acc_time(), output => top_call_trees_output()}.
Options for repeated call tree statistics.
min_time is an optional minimum accumulated time of a tree. min_count (default: 2) specifies minimum number of repetitions of a tree. max_size (default: 10) specifies maximum number of listed call trees.
-type top_call_trees_output() :: reduced | complete.
Specifies the behaviour for overlapping call trees.
reduced (default) hides subtrees, while complete keeps them.
-type tr() :: #tr{}.
Trace record, storing one collected trace event.
Record fields:index-index/0pid- process in which the traced event occurred,erlang:pid()event-call,returnorexceptionfor function traces;sendorrecvfor messages.mfa-erlang:mfa()for function traces;no_mfafor messages.data- Argument list (for calls), returned value (for returns) or class and value (for exceptions).ts- Timestamp in microseconds.info- Forsendevents it is arecipient/0tuple; otherwiseno_info.
tab/0.
-type trace_options() :: #{modules => module_spec(), pids => pids(), msg => message_event_types(), msg_trigger => msg_trigger()}.
-type trace_spec() :: #{modules := module_spec(), pids := pids(), msg := message_event_types(), msg_trigger := msg_trigger()}.
-type traced_pids_tab() :: none | ets:table().
-type tree() :: #node{}.
Function call tree node.
Record fields:-type tree_item() :: {acc_time(), call_tree_count(), tree()}.
Functions
-spec app_modules(atom()) -> [module()].
-spec call_stat(selector(Key)) -> #{Key => {call_count(), acc_time(), own_time()}}.
tab/0.See also: call_stat/2.
-spec call_stat(selector(Key), tr_source()) -> #{Key => {call_count(), acc_time(), own_time()}}.
Returns call time statistics for traces selected from tr_source/0.
Key returned by KeyF.
-spec clean() -> ok.
-spec contains_data(term(), tr()) -> boolean().
Looks for DataVal in #tr.data.
DataVal can occur in (possibly nested) tuples, maps or lists.
-spec do(tr()) -> term().
tr/0 record or index.
-spec dump(file:name_all()) -> ok | {error, any()}.
tab/0 table to a file.
tab/0.
tr_source/0.
-spec load(file:name_all()) -> {ok, table()} | {error, any()}.
Loads an ETS trace table from a file, and makes it the current table.
Fails if the table already exists.tr/0 record from tab/0 for an index.
-spec mfargs(mfa(), list()) -> mfargs().
Args in an MFA tuple.
-spec mfarity(mfa() | mfargs()) -> mfa().
Prints sorted call time statistics for the selected traces from tab/0.
acc_time/0, descending. Only top Limit rows are printed.See also: sorted_call_stat/1.
Returns a list of traces from tab/0 between the first matched call and the corresponding return.
tr/0 record. Fails if no trace is matched.See also: range/2.
-spec range(pred(), range_options()) -> [tr()].
Returns a list of traces from tr_source/0 between the first matched call and the corresponding return.
tab/0 between matched calls and corresponding returns.See also: ranges/2.
-spec ranges(pred(), range_options()) -> [[tr()]].
tr_source/0 between matched calls and corresponding returns.
-spec reduce_call_trees(ets:tid()) -> true.
-spec select() -> [tr()].
tab/0.
-spec select(selector(Data)) -> [Data].
tab/0 with ets:fun2ms(F).
-spec select(selector(Data), term()) -> [Data].
Selects data from matching traces from tab/0 with ets:fun2ms(F).
DataVal in #tr.data. DataVal can occur in (possibly nested) tuples, maps or lists.
-spec set_tab(table()) -> ok.
-spec sorted_call_stat(selector(Key)) -> [{Key, call_count(), acc_time(), own_time()}].
Returns sorted call time statistics for the selected traces from tab/0.
acc_time/0, descending.See also: call_stat/1.
-spec start() -> {ok, pid()}.
tr as a stand-alone gen_server. Intended for interactive use.See also: start/1.
-spec start(init_options()) -> {ok, pid()}.
Starts tr as a stand-alone gen_server. Intended for interactive use.
Opts.
-spec start_link() -> {ok, pid()}.
tr as part of a supervision tree.See also: start/1.
-spec start_link(init_options()) -> {ok, pid()}.
tr as part of a supervision tree.See also: start/1.
-spec stop() -> ok.
tr server process.
-spec stop_tracing() -> ok | {error, not_tracing}.
Stops tracing, disabling all trace specs.
Any future messages from the Erlang tracer will be ignored.-spec tab() -> table().
-spec top_call_trees() -> [tree_item()].
See also: top_call_trees/1.
-spec top_call_trees(top_call_trees_options()) -> [tree_item()].
Returns statistics of repeated function call trees that took most time.
Two call trees repeat if they contain the same function calls and returns in the same order taking the same arguments and returning the same values, respectively. The results are sorted according to accumulated time.-spec trace(module_spec() | trace_options()) -> ok | {error, already_tracing}.
Starts tracing of the specified functions/modules and/or message events.
You can either provide a list of modules/functions or a more generic map of options.-spec trace(module_spec(), pids()) -> ok | {error, already_tracing}.
-spec trace_app(atom()) -> ok | {error, already_tracing}.
-spec trace_apps([atom()]) -> ok | {error, already_tracing}.
Returns traceback of the first matching trace from tr_source/0.
tr record. Fails if no trace is matched.See also: traceback/2.
-spec traceback(pred(), tb_options()) -> [tr()].
Returns traceback of the first matching trace from tr_source/0.
limit and format do not apply.
tab/0.See also: tracebacks/2.
-spec tracebacks(pred(), tb_options()) -> [[tr()]] | tb_tree().
tr_source/0.
-spec ts(tr()) -> string().