From 6cb6b59cd4cd5bd4383053e12ae8ab192711c827 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Mon, 8 Feb 2016 18:31:43 +0100 Subject: erts: Extend process and port tracing This commit completes the tracing for processes so that all messages sent by a process (via nifs or otherwise) will be traced. The commit also adds tracing of all types of events from ports. When enabling tracing using erlang:trace, the 'all' flag now also enables tracing on all ports. OTP-13496 --- erts/doc/src/erlang.xml | 329 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 251 insertions(+), 78 deletions(-) (limited to 'erts/doc/src/erlang.xml') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 86bdb1dfe6..abc0d56983 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -8347,22 +8347,47 @@ timestamp() -> How == false) the trace flags in FlagList for the process or processes represented by - PidSpec.

-

PidSpec is either a process identifier - (pid) for a local process, or one of the following atoms:

+ PidPortSpec.

+

PidPortSpec is either a process identifier + (pid) for a local process, a port identifier, + or one of the following atoms:

+ all + +

All currently existing processes and ports and all that + will be created in the future.

+ + processes + +

All currently existing processes and all that will be created in the future.

+ + ports + +

All currently existing ports and all that will be created in the future.

+ existing + +

All currently existing processes and ports.

+ + existing_processes

All currently existing processes.

 + existing_ports + +

All currently existing ports.

+ new -

All processes that are created in the future.

+

All processes and ports that will be created in the future.

 - all + new_processes -

All currently existing processes and all processes that - are created in the future.

+

All processes that will be created in the future.

+ + new_ports + +

All ports that will be created in the future.

FlagList can contain any number of the @@ -8378,28 +8403,21 @@ timestamp() -> send

Traces sending of messages.

-

Message tags: send and - send_to_non_existing_process.

+

Message tags: send and + send_to_non_existing_process.

'receive'

Traces receiving of messages.

-

Message tags: 'receive'.

- - procs - -

Traces process-related events.

-

Message tags: spawn, exit, - register, unregister, link, - unlink, getting_linked, and - getting_unlinked.

+

Message tags: 'receive'.

 - call +call

Traces certain function calls. Specify which function calls to trace by calling erlang:trace_pattern/3.

-

Message tags: call and return_from.

+

Message tags: call and + return_from.

 silent @@ -8417,8 +8435,9 @@ timestamp() -> specification function {silent,Bool}, giving a high degree of control of which functions with which arguments that trigger the trace.

-

Message tags: call, return_from, and - return_to. Or rather, the absence of.

+

Message tags: call, + return_from, and + return_to. Or rather, the absence of.

 return_to @@ -8439,23 +8458,62 @@ timestamp() ->

To get trace messages containing return values from functions, use the {return_trace} match specification action instead.

-

Message tags: return_to.

+

Message tags: return_to.

+ + procs + +

Traces process-related events.

+

Message tags: spawn, + exit, + register, + unregister, + link, + unlink, + getting_linked, and + getting_unlinked.

+ + ports + +

Traces port-related events.

+

Message tags: open, + closed, + register, + unregister, + getting_linked, and + getting_unlinked.

 running

Traces scheduling of processes.

-

Message tags: in and out.

+

Message tags: in and + out.

 exiting

Traces scheduling of exiting processes.

-

Message tags: in_exiting, out_exiting, and - out_exited.

+

Message tags: in_exiting, + out_exiting, and + out_exited.

+ + running_procs + +

Traces scheduling of processes just like running. + However this option also includes schedule events when the + process executes within the context of a port without + being scheduled out itself.

+

Message tags: in and + out.

+ + running_ports + +

Traces scheduling of ports.

+

Message tags: in and + out.

 garbage_collection

Traces garbage collections of processes.

-

Message tags: gc_start and gc_end.

+

Message tags: gc_start and gc_end.

 timestamp @@ -8470,8 +8528,8 @@ timestamp() -> in CPU time, not wall clock time. That is, cpu_timestamp will not be used if monotonic_timestamp, or strict_monotonic_timestamp is enabled. - Only allowed with PidSpec==all. If the host - machine OS does not support high-resolution + Only allowed with PidPortSpec==all. If the + host machine OS does not support high-resolution CPU time measurements, trace/3 exits with badarg. Notice that most OS do not synchronize this value across cores, so be prepared @@ -8483,8 +8541,8 @@ timestamp() -> Erlang monotonic time time-stamp in all trace messages. The time-stamp (Ts) has the same format and value as produced by - erlang:monotonic_time(nano_seconds). This flag overrides - the cpu_timestamp flag.

+ erlang:monotonic_time(nano_seconds). + This flag overrides the cpu_timestamp flag.

 strict_monotonic_timestamp @@ -8493,9 +8551,9 @@ timestamp() -> monotonic time and a monotonically increasing integer in all trace messages. The time-stamp (Ts) has the same format and value as produced by - {erlang:monotonic_time(nano_seconds), - erlang:unique_integer([monotonic])}. This flag overrides - the cpu_timestamp flag.

+ {erlang:monotonic_time(nano_seconds), + erlang:unique_integer([monotonic])}. + This flag overrides the cpu_timestamp flag.

 arity @@ -8563,21 +8621,36 @@ timestamp() -> the other one will become active.

- {trace, Pid, 'receive', Msg} - -

When Pid receives message Msg.

- - {trace, Pid, send, Msg, To} + + + {trace, PidPort, send, Msg, To} + -

When Pid sends message Msg to +

When PidPort sends message Msg to process To.

 - {trace, Pid, send_to_non_existing_process, Msg, To} + + + {trace, PidPort, send_to_non_existing_process, Msg, To} + -

When Pid sends message Msg to +

When PidPort sends message Msg to the non-existing process To.

 - {trace, Pid, call, {M, F, Args}} + + + {trace, PidPort, 'receive', Msg} + + +

When PidPort receives message Msg. + If Msg is set to timeout, then a receive + statement may have timedout, or the process received + a message with the payload timeout.

+ + + + {trace, Pid, call, {M, F, Args}} +

When Pid calls a traced function. The return values of calls are never supplied, only the call and its @@ -8586,7 +8659,10 @@ timestamp() -> change the contents of this message, so that Arity is specified instead of Args.

 - {trace, Pid, return_to, {M, F, Arity}} + + + {trace, Pid, return_to, {M, F, Arity}} +

When Pid returns to the specified function. This trace message is sent if both @@ -8598,73 +8674,162 @@ timestamp() -> (that is, the functions match specification matched, and {message, false} was not an action).

 - {trace, Pid, return_from, {M, F, Arity}, ReturnValue} + + + {trace, Pid, return_from, {M, F, Arity}, ReturnValue} +

When Pid returns from the specified function. This trace message is sent if flag call is set, and the function has a match specification with a return_trace or exception_trace action.

 - {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}} + + + {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}} +

When Pid exits from the specified function because of an exception. This trace message is sent if flag call is set, and the function has a match specification with an exception_trace action.

 - {trace, Pid, spawn, Pid2, {M, F, Args}} + + + {trace, Pid, spawn, Pid2, {M, F, Args}} +

When Pid spawns a new process Pid2 with the specified function call as entry point.

Args is supposed to be the argument list, but can be any term if the spawn is erroneous.

 - {trace, Pid, exit, Reason} + + + {trace, Pid, exit, Reason} +

When Pid exits with reason Reason.

 - {trace, Pid, link, Pid2} + + + {trace, PidPort, register, RegName} + + +

When PidPort gets the name RegName registered.

+ + + + {trace, PidPort, unregister, RegName} + + +

When PidPort gets the name RegName unregistered. + This is done automatically when a registered + process or port exits.

+ + + + {trace, Pid, link, Pid2} +

When Pid links to a process Pid2.

 - {trace, Pid, unlink, Pid2} + + + {trace, Pid, unlink, Pid2} +

When Pid removes the link from a process Pid2.

 - {trace, Pid, getting_linked, Pid2} + + + {trace, PidPort, getting_linked, Pid2} + -

When Pid gets linked to a process Pid2.

+

When PidPort gets linked to a process Pid2.

 - {trace, Pid, getting_unlinked, Pid2} + + + {trace, PidPort, getting_unlinked, Pid2} + -

When Pid gets unlinked from a process Pid2.

+

When PidPort gets unlinked from a process Pid2.

 - {trace, Pid, register, RegName} + + + {trace, Pid, exit, Reason} + -

When Pid gets the name RegName registered.

+

When Pid exits with reason Reason.

 - {trace, Pid, unregister, RegName} + + + {trace, Port, open, Pid, Driver} + -

When Pid gets the name RegName unregistered. - This is done automatically when a registered - process exits.

+

When Pid opens a new port Port with + the running the Driver.

+

Driver is the name of the driver as an atom.

 - {trace, Pid, in, {M, F, Arity} | 0} + + + {trace, Port, closed, Reason} + + +

When Port closed with Reason.

+ + + + + {trace, Pid, in | in_exiting, {M, F, Arity} | 0} +

When Pid is scheduled to run. The process runs in function {M, F, Arity}. On some rare occasions, the current function cannot be determined, then the last element is 0.

 - {trace, Pid, out, {M, F, Arity} | 0} + + + + + {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} | 0} +

When Pid is scheduled out. The process was running in function {M, F, Arity}. On some rare occasions, the current function cannot be determined, then the last element is 0.

 - {trace, Pid, gc_start, Info} + + + {trace, Port, in, Command | 0} + + +

When Port is scheduled to run. Command is the + first thing the port will execute, it may however run several + commands before being scheduled out. On some rare + occasions, the current function cannot be determined, + then the last element is 0.

+

The possible commands are: call | close | command | connect | control | flush | info | link | open | unlink

+ + + + {trace, Port, out, Command | 0} + + +

When Port is scheduled out. The last command run + was Command. On some rare occasions, + the current function cannot be determined, then the last + element is 0. Command can contain the same + commands as in +

+ + + + {trace, Pid, gc_start, Info} +

Sent when garbage collection is about to be started. @@ -8706,7 +8871,10 @@ timestamp() ->

All sizes are in words.

 - {trace, Pid, gc_end, Info} + + + {trace, Pid, gc_end, Info} +

Sent when garbage collection is finished. Info contains the same kind of list as in message gc_start, @@ -8719,13 +8887,13 @@ timestamp() ->

Each process can only be traced by one tracer. Therefore, attempts to trace an already traced process fail.

Returns: A number indicating the number of processes that - matched PidSpec. - If PidSpec is a process + matched PidPortSpec. + If PidPortSpec is a process identifier, the return value is 1. - If PidSpec + If PidPortSpec is all or existing, the return value is the number of processes running. - If PidSpec is new, the return value is + If PidPortSpec is new, the return value is 0.

Failure: badarg if the specified arguments are not supported. For example, cpu_timestamp is not @@ -8787,12 +8955,15 @@ timestamp() -> -

Returns trace information about a process or function.

-

To get information about a process, - PidOrFunc is to - be a process identifier (pid) or the atom new. - The atom new means that the default trace state for - processes to be created is returned.

+

Returns trace information about a port, process or function.

+

To get information about a port or process, + PidPortOrFunc 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:

flags @@ -8802,8 +8973,10 @@ timestamp() -> traces are enabled, and one or more of the followings atoms if traces are enabled: send, 'receive', set_on_spawn, call, - return_to, procs, set_on_first_spawn, - set_on_link, running, + return_to, procs, ports, set_on_first_spawn, + set_on_link, running, running_procs, + running_ports, silent, exiting + monotonic_timestamp, strict_monotonic_timestamp, garbage_collection, timestamp, and arity. The order is arbitrary.

 @@ -8815,7 +8988,7 @@ timestamp() -> value is [].

 -

To get information about a function, PidOrFunc is to +

To get information about a function, PidPortOrFunc 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 @@ -8883,7 +9056,7 @@ timestamp() -> 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 PidOrFunc is on_load, the information +

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

-- cgit v1.2.3