tr (erlang_doctor v0.3.2)

View Source
Erlang Doctor API module.

Summary

Types

acc_time/0
call/0
call_count/0
call_stat_field/0
call_tree_count/0
call_tree_stat_options/0
call_tree_stat_state/0
erlang_trace_flags/0
index/0
init_options/0

Initialization options.

limit/0
message_event_types/0
mfargs/0
module_spec/0
msg_trigger/0

Condition checked before collecting message traces for a process.

order/0
own_time/0
pid_call_state/0
pids/0
pred/1

Predicate returning true for matching terms of type T.

prev_next_options/0

Options for obtaining previous and next traces.

range_options/0

Options for trace ranges.

range_output/0
recipient/0
result/0
selector/1

Trace selector function.

simple_tr/0
sorted_call_stat_options/0

Options for sorted call statistics.

state/0
table/0
tb_acc/0
tb_acc_list/0
tb_acc_tree/0
tb_format/0

Format in which tracebacks are returned.

tb_options/0

Traceback options.

tb_order/0
tb_output/0
tb_tree/0
top_call_trees_options/0

Options for repeated call tree statistics.

top_call_trees_output/0

Specifies the behaviour for overlapping call trees.

tr/0

Trace record, storing one collected trace event.

tr_source/0
trace_options/0
trace_spec/0
traced_pids_tab/0
tree/0

Function call tree node.

tree_item/0

Functions

app_modules(AppName)
call_stat(KeyF)
call_stat(KeyF, Tab)

Returns call time statistics for traces selected from tr_source().

clean()
contains_data(DataVal, Tr)

Returns traces containing DataVal in #tr.data.

contains_val(T, T)

Checks if the given value DataVal is present within Data.

do(Index)
dump(File)
filter(F)
filter(F, Tab)
load(File)

Loads an ETS trace table from a file, and makes it the current table.

lookup(Index)
match_data(Pred, Tr)

Returns traces with #tr.data containing any values matching the provided predicate.

match_val(Pred, T)

Checks if Val contains any values matching the predicate Pred.

mfargs(_, Args)
mfarity(_)
next(Index)
next(Index, Options)
prev(Index)
prev(Index, Options)
print_sorted_call_stat(KeyF)

Prints sorted function call statistics for the selected traces from tab().

print_sorted_call_stat(KeyF, Options)

Prints sorted function call statistics for the selected traces from tab().

range(PredF)

Returns a list of traces from tab() between the first matched call and the corresponding return.

range(Index, Options)

Returns a list of traces from tr_source() between the first matched call and the corresponding return.

ranges(PredF)
ranges(PredF, Options)
reduce_call_trees(TreeTab)
root(Tr)
roots(Trees)
select()
select(F)
select(F, DataVal)

Selects data from matching traces from tab() with ets:fun2ms(F).

seq_next(Index)
seq_prev(Index)
set_tab(Tab)
sorted_call_stat(KeyF)

Returns sorted function call statistics for the selected traces from tab().

sorted_call_stat(KeyF, Options)

Returns sorted function call statistics for the selected traces from tab().

start()
start(Opts)

Starts tr as a stand-alone gen_server. Intended for interactive use.

start_link()
start_link(Opts)
stop()
stop_tracing()

Stops tracing, disabling all trace specs.

tab()
top_call_trees()
top_call_trees(Options)

Returns statistics of repeated function call trees that took most time.

trace(Modules)

Starts tracing of the specified functions/modules and/or message events.

trace(Modules, Pids)
trace_app(App)
trace_apps(Apps)
traceback(Pred)

Returns traceback of the first matching trace from tr_source().

traceback(Index, Options)

Returns traceback of the first matching trace from tr_source().

tracebacks(PredF)
tracebacks(PredF, Options)
ts(Tr)

Types

acc_time/0

-type acc_time() :: non_neg_integer().
Total accumulated time.

call/0

-type call() :: {call, {module(), atom(), list()}}.

call_count/0

-type call_count() :: non_neg_integer().
Total number of aggregated calls.

call_stat_field/0

-type call_stat_field() :: count | acc_time | own_time.

call_tree_count/0

-type call_tree_count() :: pos_integer().
Number of occurrences of a given call tree.

call_tree_stat_options/0

-type call_tree_stat_options() :: #{tab => table()}.

call_tree_stat_state/0

-type call_tree_stat_state() :: #{pid_states := map(), tab := ets:tid()}.

erlang_trace_flags/0

-type erlang_trace_flags() :: [call | timestamp | send | 'receive'].

index/0

-type index() :: pos_integer().
Unique, auto-incremented identifier of a tr() record.

init_options/0

-type init_options() :: #{tab => table(), index => index(), limit => limit()}.

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.

limit/0

-type limit() :: pos_integer() | infinity.
Maximum number of items.

message_event_types/0

-type message_event_types() :: send | recv | all | none.
Message event types to trace. Default: none.

mfargs/0

-type mfargs() :: {module(), atom(), list()}.
Module, function and arguments.

module_spec/0

-type module_spec() :: [module() | mfa()].
Specifies traced modules and/or individual functions. Default: [].

msg_trigger/0

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

order/0

-type order() :: asc | desc.

own_time/0

-type own_time() :: non_neg_integer().
Total own time (without other called functions).

pid_call_state/0

-type pid_call_state() :: [tree() | call()].

pids/0

-type pids() :: [pid()] | all.
A list of processes to trace. Default: all.

pred/1

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

prev_next_options/0

-type prev_next_options() :: #{tab => table(), pred => pred(tr())}.

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)

range_options/0

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

range_output/0

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

-type recipient() :: {pid(), boolean()}.
Recipient pid with a boolean indicating if it exists.

result/0

-type result() :: {return | exception, any()}.
Result of a function call.

selector/1

-type selector(Data) :: fun((tr()) -> Data).

Trace selector function.

For selected traces, it returns Data. For other traces, it should fail.

simple_tr/0

-type simple_tr() :: call() | result().

sorted_call_stat_options/0

-type sorted_call_stat_options() :: #{sort_by => call_stat_field(), order => order(), limit => limit()}.

Options for sorted call statistics.

sort_by is the field to sort by (default: acc_time). order is ascending or descending (default: desc). limit is the maximum number of rows returned (default: infinity).

state/0

-type state() ::
          #{tab := table(),
            index := index(),
            limit := limit(),
            trace := none | trace_spec(),
            tracer_pid := none | pid()}.

table/0

-type table() :: atom().
ETS table name.

tb_acc/0

-type tb_acc() :: tb_acc_tree() | tb_acc_list().

tb_acc_list/0

-type tb_acc_list() :: [[tr()]].

tb_acc_tree/0

-type tb_acc_tree() :: [{tr(), tb_acc_tree()}].

tb_format/0

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

tb_options/0

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

tb_order/0

-type tb_order() :: top_down | bottom_up.
Order of calls in each returned traceback. Default: top_down.

tb_output/0

-type tb_output() :: shortest | longest | all.
Which tracebacks to return if they overlap. Default: shortest.

tb_tree/0

-type tb_tree() :: tr() | {tr(), [tb_tree()]}.
Multiple tracebacks with a common root merged into a tree structure.

top_call_trees_options/0

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

top_call_trees_output/0

-type top_call_trees_output() :: reduced | complete.

Specifies the behaviour for overlapping call trees.

reduced (default) hides subtrees, while complete keeps them.

tr/0

-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 - index()
  • pid - process in which the traced event occurred, erlang:pid()
  • event - call, return or exception for function traces; send or recv for messages.
  • mfa - erlang:mfa() for function traces; no_mfa for messages.
  • data - Argument list (for calls), returned value (for returns) or class and value (for exceptions).
  • ts - Timestamp in microseconds.
  • info - For send events it is a recipient() tuple; otherwise no_info.

tr_source/0

-type tr_source() :: table() | [tr()].
Source of traces: an ETS table or a list of traces. Default: tab().

trace_options/0

-type trace_options() ::
          #{modules => module_spec(),
            pids => pids(),
            msg => message_event_types(),
            msg_trigger => msg_trigger()}.
Options for tracing.

trace_spec/0

-type trace_spec() ::
          #{modules := module_spec(),
            pids := pids(),
            msg := message_event_types(),
            msg_trigger := msg_trigger()}.

traced_pids_tab/0

-type traced_pids_tab() :: none | ets:table().

tree/0

-type tree() ::
          #node{module :: module(),
                function :: atom(),
                args :: list(),
                children :: [#node{}],
                result :: result()}.

Function call tree node.

Record fields:
  • module - module name
  • function - function name
  • args - argument list
  • children - a list of child nodes, each of them being tree()
  • result - return value or exception, result()

tree_item/0

-type tree_item() :: {acc_time(), call_tree_count(), tree()}.
Function call tree with its accumulated time and number of repetitions.

Functions

app_modules(AppName)

-spec app_modules(atom()) -> [module()].
Returns all module names for an application.

call_stat(KeyF)

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

call_stat(KeyF, Tab)

-spec call_stat(selector(Key), tr_source()) -> #{Key => {call_count(), acc_time(), own_time()}}.

Returns call time statistics for traces selected from tr_source().

Calls are aggregated by Key returned by KeyF.

clean()

-spec clean() -> ok.
Removes all traces from the current ETS table.

contains_data(DataVal, Tr)

-spec contains_data(term(), tr()) -> boolean().

Returns traces containing DataVal in #tr.data.

DataVal can occur in (possibly nested) tuples, maps or lists.

contains_val(T, T)

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

do(Index)

-spec do(tr()) -> term().
Executes the function call for the provided tr() record or index.

dump(File)

-spec dump(file:name_all()) -> ok | {error, any()}.
Dumps the tab() table to a file.

filter(F)

-spec filter(pred(tr())) -> [tr()].
Returns matching traces from tab().

filter(F, Tab)

-spec filter(pred(tr()), tr_source()) -> [tr()].
Returns matching traces from tr_source().

load(File)

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

lookup(Index)

-spec lookup(index()) -> tr().
Returns the tr() record from tab() for an index.

match_data(Pred, Tr)

-spec match_data(pred(term()), tr()) -> boolean().

Returns traces with #tr.data containing any values matching the provided predicate.

The matching values can occur in (possibly nested) tuples, maps or lists.

match_val(Pred, T)

-spec match_val(pred(T), T) -> boolean().

Checks if Val contains any values matching the predicate Pred.

The matching values can occur in (possibly nested) tuples, maps or lists.

mfargs(_, Args)

-spec mfargs(mfa(), list()) -> mfargs().
Replaces arity with Args in an MFA tuple.

mfarity(_)

-spec mfarity(mfa() | mfargs()) -> mfa().
Replaces arguments with arity in an MFA tuple.

next(Index)

-spec next(index() | tr()) -> tr().

next(Index, Options)

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

prev(Index)

-spec prev(index() | tr()) -> tr().

prev(Index, Options)

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

range(PredF)

-spec range(pred(tr()) | index() | tr()) -> [tr()].

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 tr() record. Fails if no trace is matched.

See also: range/2.

range(Index, Options)

-spec range(pred(tr()) | index() | tr(), range_options()) -> [tr()].

Returns a list of traces from tr_source() between the first matched call and the corresponding return.

Fails if no call is matched.

ranges(PredF)

-spec ranges(pred(tr())) -> [[tr()]].
Returns lists of traces from tab() between matched calls and corresponding returns.

See also: ranges/2.

ranges(PredF, Options)

-spec ranges(pred(tr()), range_options()) -> [[tr()]].
Returns lists of traces from tr_source() between matched calls and corresponding returns.

reduce_call_trees(TreeTab)

-spec reduce_call_trees(ets:tid()) -> true.

root(Tr)

-spec root(tb_tree()) -> tr().
Returns the root call of the provided tb_tree().

roots(Trees)

-spec roots([tb_tree()]) -> [tr()].
Returns the root call of each tb_tree() from the provided list.

select()

-spec select() -> [tr()].
Returns a list of all collected traces from tab().

select(F)

-spec select(selector(Data)) -> [Data].
Selects data from matching traces from tab() with ets:fun2ms(F).

select(F, DataVal)

-spec select(selector(Data), term()) -> [Data].

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.

seq_next(Index)

-spec seq_next(index() | tr()) -> tr().

seq_prev(Index)

-spec seq_prev(index() | tr()) -> tr().

set_tab(Tab)

-spec set_tab(table()) -> ok.
Sets a new ETS table for collecting traces, creating it if it doesn't exist.

sorted_call_stat(KeyF)

-spec sorted_call_stat(selector(Key)) -> [{Key, call_count(), acc_time(), own_time()}].

Returns sorted function call statistics for the selected traces from tab().

The statistics are sorted according to acc_time(), descending.

See also: call_stat/1, sorted_call_stat/2.

sorted_call_stat(KeyF, Options)

-spec sorted_call_stat(selector(Key), sorted_call_stat_options()) ->
                          [{Key, call_count(), acc_time(), own_time()}].

Returns sorted function call statistics for the selected traces from tab().

The results can be sorted by call count or acc/own time, descending or ascending.

start()

-spec start() -> {ok, pid()}.
Starts tr as a stand-alone gen_server. Intended for interactive use.

See also: start/1.

start(Opts)

-spec start(init_options()) -> {ok, pid()}.

Starts tr as a stand-alone gen_server. Intended for interactive use.

You can override the selected Opts.

start_link()

-spec start_link() -> {ok, pid()}.
Starts tr as part of a supervision tree.

See also: start/1.

start_link(Opts)

-spec start_link(init_options()) -> {ok, pid()}.
Start tr as part of a supervision tree.

See also: start/1.

stop()

-spec stop() -> ok.
Stops the whole tr server process.

stop_tracing()

-spec stop_tracing() -> ok | {error, not_tracing}.

Stops tracing, disabling all trace specs.

Any future messages from the Erlang tracer will be ignored.

tab()

-spec tab() -> table().
Returns the name of the current ETS trace table in use.

top_call_trees()

-spec top_call_trees() -> [tree_item()].
Returns statistics of repeated function call trees that took most time.

See also: top_call_trees/1.

top_call_trees(Options)

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

trace(Modules)

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

trace(Modules, Pids)

-spec trace(module_spec(), pids()) -> ok | {error, already_tracing}.
Starts tracing of the specified functions/modules in specific processes.

trace_app(App)

-spec trace_app(atom()) -> ok | {error, already_tracing}.
Starts tracing of all modules in an application.

trace_apps(Apps)

-spec trace_apps([atom()]) -> ok | {error, already_tracing}.
Starts tracing of all modules in all provided applications.

traceback(Pred)

-spec traceback(pred(tr()) | index() | tr()) -> [tr()].

Returns traceback of the first matching trace from 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.

traceback(Index, Options)

-spec traceback(pred(tr()) | index() | tr(), tb_options()) -> [tr()] | tr() | tb_tree().

Returns traceback of the first matching trace from tr_source().

Fails if no trace is matched. The limit option does not apply.

tracebacks(PredF)

-spec tracebacks(pred(tr())) -> [[tr()]].
Returns tracebacks of all matching traces from tab().

See also: tracebacks/2.

tracebacks(PredF, Options)

-spec tracebacks(pred(tr()), tb_options()) -> [[tr()]] | [tr()] | [tb_tree()].
Returns tracebacks of all matching traces from tr_source().

ts(Tr)

-spec ts(tr()) -> string().
Returns human-readable timestamp according to RFC 3339.