A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from http://www.erlang.org/doc/apps/kernel/trace below:

trace — kernel v10.3.1

The Erlang trace interface.

The Erlang run-time system exposes several trace points that allow users to be notified when they are triggered. Trace points are things such as function calls, message sending and receiving, garbage collection, and process scheduling.

The functions in this module can be used directly, but can also be used as building blocks to build more sophisticated debugging or profiling tools. For debugging Erlang code it is recommended to use dbg and for profiling to use tprof.

Trace Sessions

All tracing is done within a trace session. Trace sessions can be created and destroyed dynamically. Each session has its own tracer that will receive all trace messages. Several sessions can exist at the same time without interfering with each other. When a trace session is destroyed, all its trace settings are automatically cleaned up.

Example:

%% Create a tracer process that will receive the trace events
1> Tracer = spawn(fun F() -> receive M -> io:format("~p~n",[M]), F() end end).
<0.91.0>
%% Create a session using the Tracer
2> Session = trace:session_create(my_session, Tracer, []).
{#Ref<0.1543805153.1548353537.92331>,{my_session, 0}}
%% Setup call tracing on self()
3> trace:process(Session, self(), true, [call]).
1
%% Setup call tracing on lists:seq/2
4> trace:function(Session, {lists,seq,2}, [], []).
1
%% Call the traced function
5> lists:seq(1, 10).
{trace,<0.89.0>,call,{lists,seq,[1,10]}} % The trace message
[1,2,3,4,5,6,7,8,9,10] % The return value
%% Cleanup the trace session
6> trace:session_destroy(Session).
ok
Node Local Tracing Only

The functions in this module only operates on the local node. That is, both the traced processes/ports as well as the tracer process/port/module must all reside on the same local node as the call is made. To trace remote nodes use dbg or ttb.

Change

This trace module was introduced in OTP 27.0. The interface and semantics are similar to the older functions erlang:trace/3, erlang:trace_pattern/3, and erlang:trace_info/2.

The main difference is the old functions operate on a single static trace session per node. That could impose the problem that different users and tools would interfere with each other's trace settings. The new trace functions in this module all operate on dynamically created trace sesssions isolated from each other. Also, this makes it easier to safely disable all trace settings when done by a single call to session_destroy/1.

To change an existing tool to use the interface the following table can be useful:

Old function call corresponds to erlang:trace(Pid, ...) process(S, Pid, ...) erlang:trace(processes, ...) process(S, all, ...) erlang:trace(existing_processes, ...) process(S, existing, ...) erlang:trace(new_processes, ...) process(S, new, ...) erlang:trace(Port, ...) port(S, Port, ...) erlang:trace(ports, ...) port(S, all, ...) erlang:trace(existing_ports, ...) port(S, existing, ...) erlang:trace(new_ports, ...) port(S, new, ...) erlang:trace(all, ...) process(S, all, ...) and port(S, all, ...) erlang:trace(existing, ...) process(S, existing, ...) and port(S, existing, ...) erlang:trace(new, ...) process(S, new, ...) and port(S, new, ...) erlang:trace_pattern(MFA, ...) function(S, MFA, ...) erlang:trace_pattern(send, ...) send(S, ...) erlang:trace_pattern('receive', ...) recv(S, ...) erlang:trace_info(...) info(S, ...)

Argument S is the trace session that must first be created with session_create/3. The other arguments (implied by ...) are mostly the same. The only other difference is that the tracer is always the tracer specified when the session was created. Options {tracer,T}, {tracer,M,S}, {meta,T}, and {meta,M,S} are therefore not allowed, and the default tracer is never the calling process.

Summary Types

A handle to an isolated trace session.

A weak session handle as returned by session_info/1. A weak session handle can be used like a full session handle, but it will not prevent the session from being destroyed when the last strong handle is garbage collected.

Functions

Enable or disable call tracing for one or more functions.

Return trace information about a port, process, function, or event.

Turn on or off trace flags for one or more ports.

Turn on or off trace flags for one or more processes.

Set trace pattern for message receiving.

Set trace pattern for message sending.

Create a new trace session.

Destroy a trace session and cleanup all its settings on processes, ports, and functions.

Return which trace sessions that affect a port, process, function, or event.

Enable/disable monitoring of system events.

Types 
-type match_variable() :: atom().

A handle to an isolated trace session.

-opaque session_strong_ref()
-opaque session_weak_ref()

A weak session handle as returned by session_info/1. A weak session handle can be used like a full session handle, but it will not prevent the session from being destroyed when the last strong handle is garbage collected.

-type system_event() ::
          busy_port | busy_dist_port | long_gc | long_message_queue | long_schedule | large_heap.
-type trace_info_flag() ::
          arity | call | exiting | garbage_collection | monotonic_timestamp | procs | ports |
          'receive' | return_to | running | running_procs | running_ports | send | set_on_first_link |
          set_on_first_spawn | set_on_link | set_on_spawn | silent | strict_monotonic_timestamp |
          timestamp.
-type trace_info_item_result() ::
          {traced, global | local | false | undefined} |
          {match_spec, trace_match_spec() | false | undefined} |
          {meta, pid() | port() | false | undefined | []} |
          {meta, module(), term()} |
          {meta_match_spec, trace_match_spec() | false | undefined} |
          {call_count, non_neg_integer() | boolean() | undefined} |
          {call_time,
           [{pid(), non_neg_integer(), non_neg_integer(), non_neg_integer()}] | boolean() | undefined} |
          {call_memory, [{pid(), non_neg_integer(), non_neg_integer()}] | boolean() | undefined}.
-type trace_pattern_flag() :: global | local | meta | call_count | call_time | call_memory.
Functions

Equivalent to erlang:trace_delivered(Tracee) except that it is run within the given session/0.

Enable or disable call tracing for one or more functions.

Must be combined with process/4 to set the call trace flag for one or more processes.

Conceptually, call tracing works as follows. In each trace session, a set of processes and a set of functions have been marked for tracing. If a traced process calls a traced function, the trace action is taken. Otherwise, nothing happens.

To add or remove one or more processes to the set of traced processes, use process/4.

Use this function to add or remove functions to the set of traced functions in a trace session.

Argument Session is the trace session to operate on as returned by session_create/3.

Argument MFA is to be a tuple, such as {Module, Function, Arity}, or the atom on_load (described below). The MFA tuple specifies the module, function, and arity for the functions to be traced. The atom '_' can be used as a wildcard in any of the following ways:

Other combinations, such as {Module,'_',Arity}, are not allowed.

If argument MFA is the atom on_load, the match specification and flag list are used on all functions in all modules that are newly loaded.

Argument MatchSpec can take the following forms:

Argument FlagList is a list of options. The following are the valid options:

Option global cannot be combined with any of the other options, which all perform some kind of local tracing. If global tracing is specified for a set of functions, then local, meta, call_count, call_time, and call_memory tracing for the matching set of functions are disabled, and vice versa.

When disabling trace, the option must match the type of trace set on the function. That is, local tracing must be disabled with option local and global tracing with option global (or no option), and so on.

Part of a match specification cannot be changed directly. If a function has a match specification, it can be replaced with a new one. Function info/3 can be used to retrieve the existing match specification.

Returns the number of functions matching argument MFA. Zero is returned if none matched or if on_load was specified.

Fails by raising an error exception with an error reason of:

-spec info(Session, PidPortFuncEvent, Item) -> Res
              when
                  Session :: session(),
                  PidPortFuncEvent ::
                      pid() |
                      port() |
                      new | new_processes | new_ports | MFA | on_load | send | 'receive' | system,
                  MFA :: {module(), atom(), arity()},
                  Item ::
                      flags | tracer | traced | match_spec | meta | meta_match_spec | call_count |
                      call_time | call_memory | all,
                  Res :: trace_info_return().

Return trace information about a port, process, function, or event.

Argument Session is the trace session to inspect as returned by session_create/3 or session_info/1.

To get information about a port or process, PidPortFuncEvent is to be a process identifier (pid), port identifier, or one of the atoms new, new_processes, or new_ports. The atom new or new_processes means that the default trace state for processes to be created is returned. The atom new_ports means that the default trace state for ports to be created is returned.

Valid Item values for ports and processes:

To get information about a function, PidPortFuncEvent is to be the three-element tuple {Module, Function, Arity} or the atom on_load. No wildcards are allowed. Returns undefined if the function does not exist or false if the function is not traced. If PidPortFuncEvent is on_load, the information returned refers to the default value for code that will be loaded.

Valid Item values for functions:

To get information about an event, PidPortFuncEvent is to be one of the atoms send or 'receive'.

One valid Item for events exists:

To get information about monitored system events, PidPortFuncEvent is to be the atom system.

Only valid Item for system is

The return value is {Item, Value}, where Value is the requested information as described earlier. If a pid for a dead process was specified, or the name of a non-existing function, Value is undefined.

Turn on or off trace flags for one or more ports.

Argument Session is the trace session to operate on as returned by session_create/3.

Ports is either a port identifier for a local port or one of the following atoms:

FlagList can contain any number of the following flags (the "message tags" refers to the list of trace messages):

The tracing process receives the trace messages described in the following list. Port is the port identifier of the traced port in which the traced event has occurred. The third tuple element is the message tag.

If flag timestamp, strict_monotonic_timestamp, or monotonic_timestamp is specified, the first tuple element is trace_ts instead, and the time stamp is added as an extra element last in the message tuple. If multiple time stamp flags are passed, timestamp has precedence over strict_monotonic_timestamp, which in turn has precedence over monotonic_timestamp. All time stamp flags are remembered, so if two are passed and the one with highest precedence later is disabled, the other one becomes active.

If a match specification (applicable only for send and 'receive' tracing) contains a {message} action function with a non-boolean value, that value is added as an extra element to the message tuple either in the last position or before the timestamp (if it is present).

Trace messages:

If the tracing process/port dies or the tracer module returns remove, the flags are silently removed.

Returns a number indicating the number of ports that matched Ports. If Ports is a port identifier, the return value is 1. If Ports is all or existing, the return value is the number of existing ports. If Ports is new, the return value is 0.

Failure: badarg if the specified arguments are not supported. For example, cpu_timestamp is not supported on all platforms.

Turn on or off trace flags for one or more processes.

Argument Session is the trace session to operate on as returned by session_create/3.

Argument Procs is either a process identifier (pid) for a local process or one of the following atoms:

Argument How is either true to turn on trace flags or false to turn them off.

Argument FlagList can contain any number of the following flags (the "message tags" refers to the list of trace messages):

The tracing process receives the trace messages described in the following list. Pid is the process identifier of the traced process in which the traced event has occurred. The third tuple element is the message tag.

If flag timestamp, strict_monotonic_timestamp, or monotonic_timestamp is specified, the first tuple element is trace_ts instead, and the time stamp is added as an extra element last in the message tuple.

If a match specification (applicable only for call, send, and 'receive' tracing) contains a {message} action function with a non-boolean value, that value is added as an extra element to the message tuple either in the last position or before the timestamp (if it is present).

Trace messages:

If the tracing process dies or the tracer module returns remove, the flags are silently removed.

Returns a number indicating the number of processes that matched Procs. If Procs is a process identifier, the return value is 1. If Procs is all or existing, the return value is the number of processes running. If Procs is new, the return value is 0.

Failure: badarg if the specified arguments are not supported. For example, cpu_timestamp is not supported on all platforms.

Set trace pattern for message receiving.

Must be combined with process/4 or port/4 to set the 'receive' trace flag for one or more processes or ports.

Argument Session is the trace session to operate on as returned by session_create/3.

The default value for the receive trace pattern in each session is true. That is, all messages received by processes having 'receive' trace enabled will be traced. Use this function to limit traced 'receive' events based on the message content, the sender, and/or the receiver.

Argument MatchSpec can take the following forms:

Argument FlagList must be [] for receive tracing.

The return value is always 1.

Examples:

Only trace messages from a specific process Pid:

> trace:recv(Session, [{['_',Pid, '_'],[],[]}], []).
1

Only trace messages matching {reply, _}:

> trace:recv(Session, [{['_','_', {reply,'_'}],[],[]}], []).
1

Only trace messages from other nodes:

> trace:recv(Session, [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
1
Note

A match specification for 'receive' trace can use all guard and body functions except caller, is_seq_trace, get_seq_token, set_seq_token, enable_trace, disable_trace, trace, silent, and process_dump.

Fails by raising an error exception with an error reason of:

Set trace pattern for message sending.

Must be combined with process/4 or port/4 to set the send trace flag for one or more processes or ports.

Argument Session is the trace session to operate on as returned by session_create/3.

The default value for the send trace pattern in each session is true. That is, all messages sent from processes having send trace enabled will be traced. Use this function to limit traced send events based on the message content, the sender, and/or the receiver.

Argument MatchSpec can take the following forms:

Argument FlagList must be [].

The return value is always 1.

Examples:

Only trace messages to a specific process Pid:

> trace:send(Session, [{[Pid, '_'],[],[]}], []).
1

Only trace messages matching {reply, _}:

> trace:send(Session, [{['_', {reply,'_'}],[],[]}], []).
1

Only trace messages sent to the sender itself:

> trace:send(Session, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
1

Only trace messages sent to other nodes:

> trace:send(Session, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
1
Note

A match specification for send trace can use all guard and body functions except caller.

Fails by raising an error exception with an error reason of:

Create a new trace session.

Argument Name is an atom name for the session. It will be returned when inspecting with session_info/1.

Argument Tracer specifies the consumer of all trace events for the session. It can be an identifier of a local process or port to receive all trace messages.

Tracer can also be a tuple {TracerModule, TracerState} for a tracer module to be called instead of sending a trace message. The tracer module can then ignore or change the trace message. For more details on how to write a tracer module, see module erl_tracer.

Argument Opts must be [].

Returns an opaque handle to the trace session. The handle will keep the session alive. If the handle is dropped and garbage collected, the session will be destroyed and cleaned up as if session_destroy/1 was called.

-spec session_destroy(Session) -> true | false when Session :: session().

Destroy a trace session and cleanup all its settings on processes, ports, and functions.

The only things not cleaned up are trace messages that have already been sent.

Returns true if the session was active. Returns false if the session had already been destroyed by either an earler call to this function or the garbage collector.

-spec session_info(PidPortFuncEvent) -> Res
                      when
                          PidPortFuncEvent ::
                              all |
                              pid() |
                              port() |
                              new | new_processes | new_ports | MFA | on_load | send | 'receive',
                          MFA :: {module(), atom(), arity()},
                          Res :: undefined | [session_weak_ref()].

Return which trace sessions that affect a port, process, function, or event.

Argument all returns all active trace sessions that exists on the node.

Returns a list of weak session handles or undefined if the process/port/function does not exists.

Enable/disable monitoring of system events.

Argument Session is the trace session to operate on as returned by session_create/3.

Argument Event is an atom describing the kind of system event to monitor. To enable monitoring argument Value is, depending on event, either a limit of that event or the atom true. To disable monitoring pass Value as the atom false.

When a monitored system event happens, a message is sent to the session tracer. The session tracer must be a process otherwise the function call will fail.

The following Events with Values can be monitored:

To disable system monitoring of a event pass the value as false. There are no other special values (like zero) to disable monitoring of an event. Some of the events have an unspecified minimum value. Lower values will be adjusted to the minimum value. For example, it is currently not possible to monitor all garbage collections with {long_gc, 0}.

Note

If the session tracer process gets so large that it itself starts to cause system monitor messages when garbage collecting, the messages enlarge the process message queue and probably make the problem worse.

Keep the tracer process neat and do not set the system monitor limits too tight.

Failures:

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4