et

v1.7.3

et

Main API of the Event Trace (ET) application

Interface module for the Event Trace (ET) application

Summary

Types

actor()

level()

Functions

phone_home(DetailLevel, FromTo, Label, Contents)

Equivalent to phone_home/5.

phone_home(DetailLevel, From, To, Label, Contents)

These functions sends a signal to the outer space and the caller hopes that someone is listening. In other words, they invoke et:trace_me/4 and et:trace_me/5 respectively.

report_event(DetailLevel, FromTo, Label, Contents)

Equivalent to report_event/5.

report_event(DetailLevel, From, To, Label, Contents)

Deprecated functions which for the time being are kept for backwards compatibility. Invokes et:trace_me/4 and et:trace_me/5 respectively.

trace_me(DetailLevel, FromTo, Label, Contents)

Invokes et:trace_me/5 with both From and To set to FromTo.

trace_me(DetailLevel, From, To, Label, Contents)

A function that is intended to be traced.

Types

actor()

(not exported)

-type actor() :: term().

level()

(not exported)

-type level() :: 0..100.

Functions

phone_home(DetailLevel, FromTo, Label, Contents)

-spec phone_home(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
                    when
                        DetailLevel :: level(),
                        FromTo :: actor(),
                        Label :: atom() | string() | term(),
                        Contents :: [{Key :: term(), Value :: term()}] | term().

Equivalent to phone_home/5.

phone_home(DetailLevel, From, To, Label, Contents)

-spec phone_home(DetailLevel, From, To, Label, Contents) -> hopefully_traced
                    when
                        DetailLevel :: level(),
                        From :: actor(),
                        To :: actor(),
                        Label :: atom() | string() | term(),
                        Contents :: [{Key :: term(), Value :: term()}] | term().

These functions sends a signal to the outer space and the caller hopes that someone is listening. In other words, they invoke et:trace_me/4 and et:trace_me/5 respectively.

report_event(DetailLevel, FromTo, Label, Contents)

-spec report_event(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
                      when
                          DetailLevel :: level(),
                          FromTo :: actor(),
                          Label :: atom() | string() | term(),
                          Contents :: [{Key :: term(), Value :: term()}] | term().

Equivalent to report_event/5.

report_event(DetailLevel, From, To, Label, Contents)

-spec report_event(DetailLevel, From, To, Label, Contents) -> hopefully_traced
                      when
                          DetailLevel :: level(),
                          From :: actor(),
                          To :: actor(),
                          Label :: atom() | string() | term(),
                          Contents :: [{Key :: term(), Value :: term()}] | term().

Deprecated functions which for the time being are kept for backwards compatibility. Invokes et:trace_me/4 and et:trace_me/5 respectively.

trace_me(DetailLevel, FromTo, Label, Contents)

(since OTP R13B04)

-spec trace_me(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
                  when
                      DetailLevel :: level(),
                      FromTo :: actor(),
                      Label :: atom() | string() | term(),
                      Contents :: [{Key :: term(), Value :: term()}] | term().

Invokes et:trace_me/5 with both From and To set to FromTo.

trace_me(DetailLevel, From, To, Label, Contents)

(since OTP R13B04)

-spec trace_me(DetailLevel, From, To, Label, Contents) -> hopefully_traced
                  when
                      DetailLevel :: level(),
                      From :: actor(),
                      To :: actor(),
                      Label :: atom() | string() | term(),
                      Contents :: [{Key :: term(), Value :: term()}] | term().

A function that is intended to be traced.

This function is intended to be invoked at strategic places in user applications in order to enable simplified tracing. The functions are extremely light weight as they do nothing besides returning an atom. The functions are designed for being traced. The global tracing mechanism in et_collector defaults to set its trace pattern to these functions.

The label is intended to provide a brief summary of the event. It is preferred to use an atom but a string would also do.

The contents can be any term but in order to simplify post processing of the traced events, a plain list of {Key, Value} tuples is preferred.

Some events, such as messages, are directed from some actor to another. Other events (termed actions) may be undirected and only have one actor.

et_collector

Collect trace events and provide a backing storage appropriate for iteration

Interface module for the Event Trace (ET) application

Summary

Types

actor()

collector_fun()

dbg_match_spec()

dbg_trace_parameters()

dbg_trace_type()

ets_match_object_pattern()

event()

event_filter_fun()

event_ts()

level()

option()

table_handle()

trace_filter_fun()

trace_ts()

Functions

change_pattern(CollectorPid, RawPattern)

Change active trace pattern globally on all trace nodes.

clear_table(Handle)

Clear the event table.

dict_delete(CollectorPid, Key)

Delete a dictionary entry and send a {et, {dict_delete, Key}} tuple to all registered subscribers.

dict_insert(CollectorPid, What, Value)

Insert a dictionary entry and send a {et, {dict_insert, Key, Val}} tuple to all registered subscribers.

dict_lookup(CollectorPid, Key)

Lookup a dictionary entry and return zero or one value.

dict_match(CollectorPid, Pattern)

Match some dictionary entries

get_global_pid()

Return a the identity of the globally registered collector if there is any.

iterate(Handle, Prev, Limit)

Equivalent to iterate(Handle, Prev, Limit, undefined, Prev).

iterate(Handle, Prev, Limit, Fun, Acc)

Iterate over the currently stored events.

make_key(Handle, Stuff)

Make a key out of an event record or an old key.

multicast(CollectorPid, Msg)

Sends a message to all registered subscribers.

report(Handle, TraceOrEvent)

Equivalent to report_event/6.

report_event(Handle, DetailLevel, FromTo, Label, Contents)

Equivalent to report_event/6.

report_event(Handle, DetailLevel, From, To, Label, Contents)

Report an event to the collector.

save_event_file(CollectorPid, FileName, Options)

Save the events to a file.

start_link(Options)

Start a collector process.

start_trace_client(CollectorPid, Type, Parameter)

Load raw Erlang trace from a file, port or process.

stop(CollectorPid)

Stop a collector process.

Types

actor()

(not exported)

-type actor() :: term().

collector_fun()

(not exported)

-type collector_fun() :: trace_filter_fun() | event_filter_fun().

dbg_match_spec()

(not exported)

-type dbg_match_spec() :: [tuple()].

dbg_trace_parameters()

(not exported)

-type dbg_trace_parameters() :: file:filename() | integer() | {string(), integer()}.

dbg_trace_type()

(not exported)

-type dbg_trace_type() :: ip | file | follow_file.

ets_match_object_pattern()

(not exported)

-type ets_match_object_pattern() :: term().

event()

(not exported)

-type event() ::
          #event{detail_level :: term(),
                 trace_ts :: term(),
                 event_ts :: term(),
                 from :: term(),
                 to :: term(),
                 label :: term(),
                 contents :: term()}.

event_filter_fun()

(not exported)

-type event_filter_fun() :: fun((Event :: event()) -> boolean() | {true, event()}).

event_ts()

(not exported)

-type event_ts() :: #event_ts{event_ts :: term(), trace_ts :: term()}.

level()

(not exported)

-type level() :: 0..100.

option()

-type option() ::
          {parent_pid, pid() | undefined} |
          {event_order, trace_ts | event_ts} |
          {dict_insert, {filter, all}, collector_fun()} |
          {dict_insert, {filter, EventFilterName :: atom()}, event_filter_fun()} |
          {dict_insert, {subscriber, pid()}, Val :: term()} |
          {dict_insert, Key :: term(), Val :: term()} |
          {dict_delete, Key :: term()} |
          {trace_client, {event_file, file:filename()} | {dbg_trace_type(), dbg_trace_parameters()}} |
          {trace_global, boolean()} |
          {trace_pattern, {module() | undefined, Level :: level() | dbg_match_spec()} | undefined} |
          {trace_port, integer()} |
          {trace_max_queue, integer()}.

table_handle()

(not exported)

-type table_handle() ::
          #table_handle{collector_pid :: term(),
                        event_tab :: term(),
                        event_order :: term(),
                        filter :: term()}.

trace_filter_fun()

(not exported)

-type trace_filter_fun() :: fun((TraceData :: tuple()) -> boolean() | {true, event()}).

trace_ts()

(not exported)

-type trace_ts() :: #trace_ts{trace_ts :: term(), event_ts :: term()}.

Functions

change_pattern(CollectorPid, RawPattern)

-spec change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
                        when
                            CollectorPid :: pid(),
                            RawPattern :: {module(), min | max | level()},
                            TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}].

Change active trace pattern globally on all trace nodes.

clear_table(Handle)

-spec clear_table(Handle) -> ok when Handle :: CollectorPid | table_handle(), CollectorPid :: pid().

Clear the event table.

dict_delete(CollectorPid, Key)

-spec dict_delete(CollectorPid :: pid(), Key :: term()) -> ok.

Delete a dictionary entry and send a {et, {dict_delete, Key}} tuple to all registered subscribers.

If the deleted entry is a registered subscriber, it will imply that the subscriber process gets is unregistered as subscriber as well as it gets it final message.

dict_insert(CollectorPid, What, Value)

-spec dict_insert(CollectorPid, What, Value) -> ok
                     when
                         CollectorPid :: pid(),
                         What :: {filter, atom()} | {subscriber, pid()} | Key,
                         Key :: term(),
                         Value :: collector_fun() | term().

Insert a dictionary entry and send a {et, {dict_insert, Key, Val}} tuple to all registered subscribers.

If the entry is a new subscriber, it will imply that the new subscriber process first will get one message for each already stored dictionary entry, before it and all old subscribers will get this particular entry. The collector process links to and then supervises the subscriber process. If the subscriber process dies it will imply that it gets unregistered as with a normal dict_delete/2.

dict_lookup(CollectorPid, Key)

-spec dict_lookup(CollectorPid :: pid(), Key :: term()) -> [Val :: term()].

Lookup a dictionary entry and return zero or one value.

dict_match(CollectorPid, Pattern)

-spec dict_match(CollectorPid :: pid(), {KeyPattern, ValPattern}) -> [Match]
                    when
                        KeyPattern :: ets_match_object_pattern(),
                        ValPattern :: ets_match_object_pattern(),
                        Match :: {Key :: term(), Val :: term()}.

Match some dictionary entries

get_global_pid()

-spec get_global_pid() -> CollectorPid :: pid().

Return a the identity of the globally registered collector if there is any.

iterate(Handle, Prev, Limit)

-spec iterate(Handle, Prev, Limit) -> NewAcc
                 when
                     Handle :: CollectorPid | table_handle(),
                     CollectorPid :: pid(),
                     Prev :: first | last | term(),
                     Limit :: Done | Forward | Backward,
                     Done :: 0,
                     Forward :: pos_integer(),
                     Backward :: neg_integer(),
                     NewAcc :: term().

Equivalent to iterate(Handle, Prev, Limit, undefined, Prev).

iterate(Handle, Prev, Limit, Fun, Acc)

-spec iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
                 when
                     Handle :: CollectorPid | table_handle(),
                     CollectorPid :: pid(),
                     Prev :: first | last | term(),
                     Limit :: Done | Forward | Backward,
                     Done :: 0,
                     Forward :: pos_integer() | infinity,
                     Backward :: neg_integer() | '-infinity',
                     Fun :: fun((event(), Acc) -> NewAcc) | undefined,
                     Acc :: term(),
                     NewAcc :: term().

Iterate over the currently stored events.

Iterates over the currently stored events and applies a function for each event. The iteration may be performed forwards or backwards and may be limited to a maximum number of events (abs(Limit)).

make_key(Handle, Stuff)

-spec make_key(Handle, Stuff) -> Key
                  when
                      Handle :: table_handle() | trace_ts | event_ts,
                      Stuff :: event() | Key,
                      Key :: event_ts() | trace_ts().

Make a key out of an event record or an old key.

multicast(CollectorPid, Msg)

-spec multicast(CollectorPid :: pid(), Msg :: term()) -> ok.

Sends a message to all registered subscribers.

report(Handle, TraceOrEvent)

-spec report(Handle, TraceOrEvent) -> {ok, Continuation}
                when
                    Handle :: table_handle() | (CollectorPid :: pid()),
                    TraceOrEvent :: event() | TraceData | end_of_trace,
                    TraceData :: tuple(),
                    Continuation :: table_handle().

Equivalent to report_event/6.

report_event(Handle, DetailLevel, FromTo, Label, Contents)

-spec report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Continuation}
                      when
                          Handle :: CollectorPid :: pid() | table_handle(),
                          DetailLevel :: level(),
                          FromTo :: actor(),
                          Label :: term(),
                          Contents :: [{Key :: term(), Value :: term()}] | term(),
                          Continuation :: table_handle().

Equivalent to report_event/6.

report_event(Handle, DetailLevel, From, To, Label, Contents)

-spec report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok, Continuation}
                      when
                          Handle :: CollectorPid :: pid() | table_handle(),
                          DetailLevel :: level(),
                          From :: actor(),
                          To :: actor(),
                          Label :: term(),
                          Contents :: [{Key :: term(), Value :: term()}] | term(),
                          Continuation :: table_handle().

Report an event to the collector.

All events are filtered thru the collector filter, which optionally may transform or discard the event. The first call should use the pid of the collector process as report handle, while subsequent calls should use the table handle.

save_event_file(CollectorPid, FileName, Options)

-spec save_event_file(CollectorPid, FileName, [Option]) -> ok | {error, term()}
                         when
                             CollectorPid :: pid(),
                             FileName :: file:filename(),
                             Option :: existing | write | append | keep | clear.

Save the events to a file.

By default the currently stored events (existing) are written to a brand new file (write) and the events are kept (keep) after they have been written to the file.

Instead of keeping the events after writing them to file, it is possible to remove all stored events after they have successfully written to file (clear).

The options defaults to existing, write and keep.

start_link(Options)

-spec start_link(Options) -> {ok, Pid :: pid()} | {error, term()} when Options :: [option()].

Start a collector process.

The collector collects trace events and keeps them ordered by their timestamp. The timestamp may either reflect the time when the actual trace data was generated (trace_ts) or when the trace data was transformed into an event record (event_ts). If the time stamp is missing in the trace data (missing timestamp option to erlang:trace/4) the trace_ts will be set to the event_ts.

Events are reported to the collector directly with the report function or indirectly via one or more trace clients. All reported events are first filtered thru the collector filter before they are stored by the collector. By replacing the default collector filter with a customized dito it is possible to allow any trace data as input. The collector filter is a dictionary entry with the predefined key {filter, collector} and the value is a fun of arity 1. See et_selector:make_event/1 for interface details, such as which erlang:trace/1 tuples that are accepted.

The collector has a built-in dictionary service. Any term may be stored as value in the dictionary and bound to a unique key. When new values are inserted with an existing key, the new values will overwrite the existing ones. Processes may subscribe on dictionary updates by using {subscriber, pid()} as dictionary key. All dictionary updates will be propagated to the subscriber processes matching the pattern {{subscriber, ''}, ''} where the first '_' is interpreted as a pid().

In global trace mode, the collector will automatically start tracing on all connected Erlang nodes. When a node connects, a port tracer will be started on that node and a corresponding trace client on the collector node.

Default values:

parent_pid - self().

event_order - trace_ts.

trace_global - false.

trace_pattern - undefined.

trace_port - 4711.

trace_max_queue - 50.

start_trace_client(CollectorPid, Type, Parameter)

-spec start_trace_client(CollectorPid, Type, Parameter) -> file_loaded | {trace_client_pid, pid()}
                            when
                                CollectorPid :: pid(),
                                Type :: event_file | dbg_trace_type(),
                                Parameter :: dbg_trace_parameters().

Load raw Erlang trace from a file, port or process.

stop(CollectorPid)

-spec stop(pid()) -> ok.

Stop a collector process.

et_selector

Define event transforms and trace patterns

Summary

Types

event()

level()

Functions

change_pattern(Pattern)

Activates/deactivates tracing by changing the current trace pattern.

make_pattern(RawPattern)

Makes a trace pattern suitable to feed change_pattern/1

parse_event(Mod, ValidTraceData)

Transforms trace data and makes an event record out of it.

Types

event()

(not exported)

-type event() ::
          #event{detail_level :: term(),
                 trace_ts :: term(),
                 event_ts :: term(),
                 from :: term(),
                 to :: term(),
                 label :: term(),
                 contents :: term()}.

level()

(not exported)

-type level() :: 0..100.

Functions

change_pattern(Pattern)

-spec change_pattern({Mod :: module(), Pattern}) -> ok
                        when
                            Pattern :: DetailLevel | TracePattern | EmptyTracePattern,
                            DetailLevel :: level(),
                            TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}],
                            EmptyTracePattern :: [].

Activates/deactivates tracing by changing the current trace pattern.

min detail level deactivates tracing of calls to et:trace_me/4,5

max detail level activates tracing of all calls to et:trace_me/4,5

integer(X) detail level activates tracing of all calls to et:trace_me/4,5 whose detail level argument is lesser than X.

An empty match spec deactivates tracing of calls to et:trace_me/4,5

Other match specs activates tracing of calls to et:trace_me/4,5 accordingly with erlang:trace_pattern/2.

make_pattern(RawPattern)

-spec make_pattern({Mod :: module(), RawPattern}) -> {Mod :: module(), TracePattern}
                      when
                          RawPattern :: level(),
                          TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}].

Makes a trace pattern suitable to feed change_pattern/1

Min detail level deactivates tracing of calls to et:trace_me/4,5

Max detail level activates tracing of all calls to et:trace_me/4,5

integer(X) detail level activates tracing of all calls to et:trace_me/4,5 whose detail level argument is lesser than X.

See also erlang:trace_pattern/2 for more info about its match_spec()

parse_event(Mod, ValidTraceData)

-spec parse_event(Mod, ValidTraceData) -> boolean | {true, event()}
                     when
                         Mod :: module(),
                         ValidTraceData :: ErlangTraceData | event(),
                         ErlangTraceData ::
                             {trace, pid(), atom(), term()} |
                             {trace, pid(), atom(), term(), term()} |
                             {trace_ts, pid(), atom(), term(), TS :: {integer(), integer(), integer()}} |
                             {trace_ts,
                              pid(),
                              atom(),
                              term(),
                              term(),
                              TS :: {integer(), integer(), integer()}} |
                             {seq_trace, atom(), term()} |
                             {seq_trace, atom(), term(), TS :: {integer(), integer(), integer()}} |
                             {drop, integer()}.

Transforms trace data and makes an event record out of it.

See erlang:trace/3 for more info about the semantics of the trace data.

An event record consists of the following fields:

detail_level - Noise has a high level as opposed to essentials.

trace_ts - Time when the trace was generated. Same as event_ts if omitted in trace data.

event_ts - Time when the event record was created.

from - From actor, such as sender of a message.

to - To actor, such as receiver of message.

label - Label intended to provide a brief event summary.

contents - All nitty gritty details of the event.

See et:trace_me/4and et:trace_me/5 for details.

Returns:

{true, Event} - where Event is an #event{} record representing the trace data

true - means that the trace data already is an event record and that it is valid as it is. No transformation is needed.

false - means that the trace data is uninteresting and should be dropped

et_viewer

Displays a sequence chart for trace events (messages/actions)

Summary

Types

actors()

first_key()

option()

Functions

file(FileName)

Start a new event viewer and a corresponding collector and load them with trace events from a trace file.

get_collector_pid(ViewerPid)

Returns the identifier of the collector process.

start()

Simplified start of a sequence chart viewer with global tracing activated.

start(GUIorOptions)

Start of a sequence chart viewer without linking to the parent process.

start_link(GUIorOptions)

Start a sequence chart viewer for trace events (messages/actions)

stop(ViewerPid)

Stops a viewer process.

Types

actors()

(not exported)

-type actors() :: [term()].

first_key()

(not exported)

-type first_key() :: term().

option()

(not exported)

-type option() ::
          {title, string()} |
          {detail_level, 0..100} |
          {is_suspended, boolean()} |
          {scale, integer()} |
          {width, integer()} |
          {height, integer()} |
          {collector_pid, pid() | undefined} |
          {active_filter, atom()} |
          {max_events, integer() | undefined} |
          {max_actors, integer() | undefined} |
          {actors, actors()} |
          {first_event, first_key()} |
          {hide_unknown, boolean()} |
          {hide_actions, boolean()} |
          {display_mode, all | {search_actors, forward | reverse, first_key(), actors()}}.

Functions

file(FileName)

-spec file(FileName :: file:filename()) -> {ok, pid()} | {error, term()}.

Start a new event viewer and a corresponding collector and load them with trace events from a trace file.

get_collector_pid(ViewerPid)

-spec get_collector_pid(ViewerPid :: pid()) -> pid().

Returns the identifier of the collector process.

start()

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

Simplified start of a sequence chart viewer with global tracing activated.

Convenient to be used from the command line (erl -s et_viewer).

start(GUIorOptions)

-spec start(GUIorOptions) -> {ok, Viewer :: pid()} | {error, term()}
               when
                   GUIorOptions :: wx | default | Options, Options :: [option() | et_collector:option()].

Start of a sequence chart viewer without linking to the parent process.

start_link(GUIorOptions)

-spec start_link(GUIorOptions) -> {ok, Viewer :: pid()} | {error, term()}
                    when
                        GUIorOptions :: wx | default | Options,
                        Options :: [option() | et_collector:option()].

Start a sequence chart viewer for trace events (messages/actions)

A filter_fun() takes an event record as sole argument and returns false | true | {true, NewEvent}.

If the collector_pid is undefined a new et_collector will be started with the following parameter settings: parent_pid, event_order, trace_global, trace_pattern, trace_port, trace_max_queue, trace_client, dict_insert and dict_delete. The new et_viewer will register itself as an et_collector subscriber.

Default values:

parent_pid - self().

title - "et_viewer".

detail_level - max.

is_suspended - false.

scale - 2.

width - 800.

height - 600.

collector_pid - undefined.

event_order - trace_ts.

active_filter - collector.

max_actors - 5.

actors - ["UNKNOWN"].

first_event - first.

hide_unknown - false.

hide_actions - false.

display_mode - all.

stop(ViewerPid)

-spec stop(ViewerPid :: pid()) -> ok.

Stops a viewer process.