From e75fdd38b04896fa6a1ac7b2fdea18ef485c70b3 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Fri, 22 Jan 2016 20:10:11 +0100 Subject: erts: Clarify docs for trace_pattern/3 --- erts/doc/src/erlang.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 423ccdf98f..c7b5ea8867 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -9199,7 +9199,8 @@ timestamp() -> true -

Enables tracing for the matching functions.

+

Enables tracing for the matching functions. + Any match specification is removed.

 MatchSpecList -- cgit v1.2.3 From 36e9d73aa08930ddf3e3587addfb9a647a41b3e7 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 6 Apr 2016 15:05:10 +0200 Subject: erts: Add docs for trace_pattern with 'send' and 'receive' --- erts/doc/src/erlang.xml | 140 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 134 insertions(+), 6 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index c7b5ea8867..f88d05cdc3 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -9124,27 +9124,155 @@ timestamp() -> - Sets trace patterns for global call tracing. + Sets trace patterns for call, send or 'receive' tracing.

The same as - erlang:trace_pattern(MFA, MatchSpec, []), + erlang:trace_pattern(Event, MatchSpec, []), retained for backward compatibility.

 - + + Sets trace pattern for message sending. + +

Sets trace pattern for message sending. + Must be combined with + erlang:trace/3 + to set the send trace flag for one or more processes. + By default all messages, sent from send traced processes, + are traced. Use erlang:trace_pattern/3 to limit + traced send events based on the message content, the sender + and/or the receiver.

+

Argument MatchSpec can take the + following forms:

+ + MatchSpecList + +

A list of match specifications. The matching is done + on the list [Receiver, Msg]. Receiver + is the process or port identity of the receiver and + Msg is the message term. The pid of the sending + process can be accessed with the guard function + self/0. An empty list is the same as true. + See the users guide section + Match Specifications in Erlang + for more information.

+ + true + +

Enables tracing for all sent messages (from send + traced processes). Any match specification is + removed. This is the default.

+ + false + +

Disables tracing for all sent messages. + Any match specification is removed.

+ + +

Argument FlagList must be [] + for send tracing.

+

The return value is always 1.

+

Example; only trace messages to a specific process Pid:

+ 
+> erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
+1
+

Only trace messages matching {reply, _}:

+ 
+> erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
+1
+

Only trace messages sent to the sender itself:

+ 
+> erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
+1
+

Only trace messages sent to other nodes:

+ 
+> erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
+1
+

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

 + + + + + + Sets trace pattern for tracing of message receiving. + +

+

Sets trace pattern for message receiving. + Must be combined with + erlang:trace/3 + to set the 'receive' trace flag for one or more processes. + By default all messages, received by 'receive' traced processes, + are traced. Use erlang:trace_pattern/3 to limit + traced receive events based on the message content, the sender + and/or the receiver.

+

Argument MatchSpec can take the + following forms:

+ + MatchSpecList + +

A list of match specifications. The matching is done + on the list [Node, Sender, Msg]. Node + is the node name of the sender. Sender is the + process or port identity of the sender, or the atom + undefined if the sender is not known (which may + be the case for remote senders). Msg is the + message term. The pid of the receiving process can be + accessed with the guard function self/0. An empty + list is the same as true. See the users guide section + Match Specifications in Erlang + for more information.

+ + true + +

Enables tracing for all received messages (to 'receive' + traced processes). Any match specification is + removed. This is the default.

+ + false + +

Disables tracing for all sent messages. + Any match specification is removed.

+ + +

Argument FlagList must be [] + for receive tracing.

+

The return value is always 1.

+

Example; only trace messages from a specific process Pid:

+ 
+> erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
+1
+

Only trace messages matching {reply, _}:

+ 
+> erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
+1
+

Only trace messages from other nodes:

+ 
+> erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
+1
+

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.

 + + + + + Sets trace patterns for tracing of function calls. -

Enables or disables call tracing for - one or more functions. Must be combined with +

Enables or disables call tracing for one or more functions. + Must be combined with erlang:trace/3 - to set the call trace flag for one or more processes.

+ to set the call trace flag + for one or more processes.

Conceptually, call tracing works as follows. Inside the Erlang Virtual Machine, a set of processes and a set of functions are to be traced. If a traced process -- cgit v1.2.3 From d0ffd5c2a84d15d94dcbc8bac98d527bfc1d4a3c Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Mon, 2 May 2016 12:29:25 +0200 Subject: erts: Fix missing type in doc for trace_pattern --- erts/doc/src/erlang.xml | 2 ++ 1 file changed, 2 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index f88d05cdc3..f42923a009 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -9137,6 +9137,7 @@ timestamp() -> Sets trace pattern for message sending. +

Sets trace pattern for message sending. Must be combined with @@ -9200,6 +9201,7 @@ timestamp() -> Sets trace pattern for tracing of message receiving. +

Sets trace pattern for message receiving. -- cgit v1.2.3 From 54172674e71caf7da7a0b069c9bd92543e4f705d Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 4 May 2016 14:45:05 +0200 Subject: erts: Add send and 'receive' to trace_info/2 to obtain match specs --- erts/doc/src/erlang.xml | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index f42923a009..5af4f0bd66 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -9015,16 +9015,16 @@ timestamp() -> -

Returns trace information about a port, process or function.

-

To get information about a port or process, - PidPortOrFunc is to +

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

+

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

-

The following Items are valid:

+

The following Items are valid for ports and processes:

flags @@ -9048,12 +9048,15 @@ timestamp() -> value is [].

 -

To get information about a function, PidPortOrFunc is to +

To get information about a function, PidPortFuncEvent is to be the three-element tuple {Module, Function, Arity} or the atom on_load. No wild cards are allowed. Returns undefined if the function does not exist, or - false if the function is not traced.

-

The following Items are valid::

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

+ +

The following Items are valid for functions:

traced @@ -9112,13 +9115,21 @@ timestamp() -> is active for this function.

 +

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

+

The only valid Item for events is:

+ + match_spec + +

Returns the match specification for this event, if it + has one, or true if no match specification has been + set.

+ +

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

-

If PidPortOrFunc is on_load, the information - returned refers to the default value for code that will be - loaded.

 @@ -9237,7 +9248,7 @@ timestamp() -> false -

Disables tracing for all sent messages. +

Disables tracing for all received messages. Any match specification is removed.

 -- cgit v1.2.3