View Source tr (erlang_doctor v0.3.0)
Erlang Doctor API module.
Summary
Types
Total accumulated time.
Total number of aggregated calls.
Number of occurrences of a given call tree.
Unique, auto-incremented identifier of a t:tr() record.
Initialization options.
Maximum number of items.
Message event types to trace. Default: none.
Module, function and arguments.
Specifies traced modules and/or individual functions. Default: [].
Condition checked before collecting message traces for a process.
Total own time (without other called functions).
A list of processes to trace. Default: all.
Predicate returning true for matching terms of type T.
Options for obtaining previous and next traces.
Options for trace ranges.
Which ranges to return. Incomplete ranges are missing at least one return. By default, all ranges are returned.
Recipient pid with a boolean indicating if it exists.
Result of a function call.
Trace selector function.
ETS table name.
Format in which tracebacks are returned.
Traceback options.
Order of calls in each returned traceback. Default: top_down.
Which tracebacks to return if they overlap. Default: shortest.
Multiple tracebacks with a common root merged into a tree structure.
Options for repeated call tree statistics.
Specifies the behaviour for overlapping call trees.
Trace record, storing one collected trace event.
Source of traces: an ETS table or a list of traces. Default: tab().
Options for tracing.
Function call tree node.
Function call tree with its accumulated time and number of repetitions.
Functions
Returns all module names for an application.
Returns call time statistics for traces selected from tab().
Returns call time statistics for traces selected from t:tr_source().
Removes all traces from the current ETS table.
Returns traces containing DataVal in #tr.data.
Checks if the given value DataVal is present within Data.
Executes the function call for the provided t:tr() record or index.
Dumps the tab() table to a file.
Returns matching traces from tab().
Returns matching traces from t:tr_source().
Loads an ETS trace table from a file, and makes it the current table.
Returns the t:tr() record from tab() for an index.
Returns traces with #tr.data containing any values matching the provided predicate.
Checks if Val contains any values matching the predicate Pred.
Replaces arity with Args in an MFA tuple.
Replaces arguments with arity in an MFA tuple.
Returns the next trace after the provided index or a trace record. The traces can be filtered by the provided predicate.
Returns the previous trace before the provided index or a trace record. The traces can be filtered by the provided predicate.
Prints sorted call time statistics for the selected traces from tab().
Returns a list of traces from tab() between the first matched call and the corresponding return.
Returns a list of traces from t:tr_source() between the first matched call and the corresponding return.
Returns lists of traces from tab() between matched calls and corresponding returns.
Returns lists of traces from t:tr_source() between matched calls and corresponding returns.
Returns the root call of the provided t:tb_tree().
Returns the root call of each t:tb_tree() from the provided list.
Returns a list of all collected traces from tab().
Selects data from matching traces from tab() with ets:fun2ms(F).
Selects data from matching traces from tab() with ets:fun2ms(F).
Sets a new ETS table for collecting traces, creating it if it doesn't exist.
Returns sorted call time statistics for the selected traces from tab().
Starts tr as a stand-alone gen_server. Intended for interactive use.
Starts tr as a stand-alone gen_server. Intended for interactive use.
Starts tr as part of a supervision tree.
Start tr as part of a supervision tree.
Stops the whole tr server process.
Stops tracing, disabling all trace specs.
Returns the name of the current ETS trace table in use.
Returns statistics of repeated function call trees that took most time.
Returns statistics of repeated function call trees that took most time.
Starts tracing of the specified functions/modules and/or message events.
Starts tracing of the specified functions/modules in specific processes.
Starts tracing of all modules in an application.
Starts tracing of all modules in all provided applications.
Returns traceback of the first matching trace from t:tr_source().
Returns traceback of the first matching trace from t:tr_source().
Returns tracebacks of all matching traces from tab().
Returns tracebacks of all matching traces from t:tr_source().
Returns human-readable timestamp according to RFC 3339.
Types
-type acc_time() :: non_neg_integer().
Total accumulated time.
-type call_count() :: non_neg_integer().
Total number of aggregated calls.
-type call_tree_count() :: pos_integer().
Number of occurrences of a given call tree.
-type call_tree_stat_options() :: #{tab => table()}.
-type erlang_trace_flags() :: [call | timestamp | send | 'receive'].
-type index() :: pos_integer().
Unique, auto-incremented identifier of a t:tr() 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.
Maximum number of items.
-type message_event_types() :: send | recv | all | none.
Message event types to trace. Default: none.
Module, function and arguments.
Specifies traced modules and/or individual functions. Default: [].
-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().
Total own time (without other called functions).
-type pids() :: [pid()] | all.
A list of processes to trace. Default: all.
-type pred(T) :: fun((T) -> boolean()).
Predicate returning true for matching terms of type T.
For other terms, it can return a different value or fail.
Options for obtaining previous and next traces.
tab is the ETS table with traces (default: trace). pred allows to filter the matching traces (default: allow any trace)
-type range_options() :: #{tab => tr_source(), max_depth => limit(), output => range_output()}.
Options for trace ranges.
Optional limit is the maximum depth of calls in the returned ranges. All traces (including messages) exceeding that depth are skipped.
-type range_output() :: complete | incomplete | all.
Which ranges to return. Incomplete ranges are missing at least one return. By default, all ranges are returned.
Recipient pid with a boolean indicating if it exists.
-type result() :: {return | exception, any()}.
Result of a function call.
-type selector(Data) :: fun((tr()) -> Data).
Trace selector function.
For selected traces, it returns Data. 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().
ETS table name.
-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() :: list | tree | root.
Format in which tracebacks are returned.
list (default) returns a list of tracebacks. tree merges them into a list of trees. root returns only the root of each tree.
-type tb_options() :: #{tab => tr_source(), output => tb_output(), format => tb_format(), order => tb_order(), limit => limit()}.
Traceback options.
Optional limit is the maximum number of tracebacks to collect before filtering them according to output.
-type tb_order() :: top_down | bottom_up.
Order of calls in each returned traceback. Default: top_down.
-type tb_output() :: shortest | longest | all.
Which tracebacks to return if they overlap. Default: shortest.
Multiple tracebacks with a common root merged into a tree structure.
-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{index :: index(), pid :: pid(), event :: call | return | exception | send | recv, mfa :: mfa() | no_mfa, data :: term(), ts :: integer(), info :: recipient() | no_info}.
Trace record, storing one collected trace event.
Record fields:
index-t:index()pid- process in which the traced event occurred,t:erlang:pid()event-call,returnorexceptionfor function traces;sendorrecvfor messages.mfa-t: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 at:recipient()tuple; otherwiseno_info.
Source of traces: an ETS table or a list of traces. Default: tab().
-type trace_options() :: #{modules => module_spec(), pids => pids(), msg => message_event_types(), msg_trigger => msg_trigger()}.
Options for tracing.
-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{module :: module(), function :: atom(), args :: list(), children :: [#node{}], result :: result()}.
Function call tree node.
Record fields:
module- module namefunction- function nameargs- argument listchildren- a list of child nodes, each of them beingt:tree()result- return value or exception,t:result()
-type tree_item() :: {acc_time(), call_tree_count(), tree()}.
Function call tree with its accumulated time and number of repetitions.
Functions
Returns all module names for an application.
-spec call_stat(selector(Key)) -> #{Key => {call_count(), acc_time(), own_time()}}.
Returns call time statistics for traces selected from tab().
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 t:tr_source().
Calls are aggregated by Key returned by KeyF.
-spec clean() -> ok.
Removes all traces from the current ETS table.
Returns traces containing DataVal in #tr.data.
DataVal can occur in (possibly nested) tuples, maps or lists.
-spec contains_val(T, T) -> boolean().
Checks if the given value DataVal is present within Data.
Returns true if DataVal is found, otherwise returns false. DataVal can occur in (possibly nested) tuples, maps or lists.
Executes the function call for the provided t:tr() record or index.
-spec dump(file:name_all()) -> ok | {error, any()}.
Dumps the tab() table to a file.
Returns matching traces from tab().
Returns matching traces from t:tr_source().
-spec load(file:name_all()) -> {ok, table()} | {error, any()}.
Loads an ETS trace table from a file, and makes it the current table.
Overwrites the current table if it is empty.
Returns the t:tr() record from tab() for an index.
Returns traces with #tr.data containing any values matching the provided predicate.
The matching values can occur in (possibly nested) tuples, maps or lists.
Checks if Val contains any values matching the predicate Pred.
The matching values can occur in (possibly nested) tuples, maps or lists.
Replaces arity with Args in an MFA tuple.
Replaces arguments with arity in an MFA tuple.
-spec next(index() | tr(), prev_next_options()) -> tr().
Returns the next trace after the provided index or a trace record. The traces can be filtered by the provided predicate.
-spec prev(index() | tr(), prev_next_options()) -> tr().
Returns the previous trace before the provided index or a trace record. The traces can be filtered by the provided predicate.
Prints sorted call time statistics for the selected traces from tab().
The statistics are sorted according to t:acc_time(), descending. Only top Limit rows are printed.
See also: sorted_call_stat/1.
Returns a list of traces from tab() between the first matched call and the corresponding return.
Matching can be done with a predicate function, an index value or a t:tr() record. Fails if no trace is matched.
See also: range/2.
Returns a list of traces from t:tr_source() between the first matched call and the corresponding return.
Fails if no call is matched.
Returns lists of traces from tab() between matched calls and corresponding returns.
See also: ranges/2.
-spec ranges(pred(tr()), range_options()) -> [[tr()]].
Returns lists of traces from t:tr_source() between matched calls and corresponding returns.
-spec reduce_call_trees(ets:tid()) -> true.
Returns the root call of the provided t:tb_tree().
Returns the root call of each t:tb_tree() from the provided list.
-spec select() -> [tr()].
Returns a list of all collected traces from tab().
-spec select(selector(Data)) -> [Data].
Selects data from matching traces from tab() with ets:fun2ms(F).
Selects data from matching traces from tab() with ets:fun2ms(F).
Additionally, the selected traces have to contain DataVal in #tr.data. DataVal can occur in (possibly nested) tuples, maps or lists.
-spec set_tab(table()) -> ok.
Sets a new ETS table for collecting traces, creating it if it doesn't exist.
-spec sorted_call_stat(selector(Key)) -> [{Key, call_count(), acc_time(), own_time()}].
Returns sorted call time statistics for the selected traces from tab().
The statistics are sorted according to t:acc_time(), descending.
See also: call_stat/1.
-spec start() -> {ok, pid()}.
Starts 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.
You can override the selected Opts.
-spec start_link() -> {ok, pid()}.
Starts tr as part of a supervision tree.
See also: start/1.
-spec start_link(init_options()) -> {ok, pid()}.
Start tr as part of a supervision tree.
See also: start/1.
-spec stop() -> ok.
Stops the whole 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().
Returns the name of the current ETS trace table in use.
-spec top_call_trees() -> [tree_item()].
Returns statistics of repeated function call trees that took most time.
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}.
Starts tracing of the specified functions/modules in specific processes.
-spec trace_app(atom()) -> ok | {error, already_tracing}.
Starts tracing of all modules in an application.
-spec trace_apps([atom()]) -> ok | {error, already_tracing}.
Starts tracing of all modules in all provided applications.
Returns traceback of the first matching trace from t:tr_source().
Matching can be done with a predicate function, an index value or a tr record. Fails if no trace is matched.
See also: traceback/2.
Returns traceback of the first matching trace from t:tr_source().
Fails if no trace is matched. The options limit and format do not apply.
Returns tracebacks of all matching traces from tab().
See also: tracebacks/2.
-spec tracebacks(pred(tr()), tb_options()) -> [[tr()]] | [tb_tree()].
Returns tracebacks of all matching traces from t:tr_source().
Returns human-readable timestamp according to RFC 3339.