aboutsummaryrefslogtreecommitdiffstats
path: root/lib/observer/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/observer/doc')
-rw-r--r--lib/observer/doc/src/observer_ug.xml111
-rw-r--r--lib/observer/doc/src/ttb.xml56
2 files changed, 126 insertions, 41 deletions
diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml
index ca354df864..6eb72f3e58 100644
--- a/lib/observer/doc/src/observer_ug.xml
+++ b/lib/observer/doc/src/observer_ug.xml
@@ -168,7 +168,7 @@
<item><p>The length of the message queue for the process.</p></item>
</taglist>
- <p>Option <em>Process info</em> opens a detailed information window on the selected process,
+ <p>Option <em>Process info</em> opens a detailed information window on the process under the mouse pointer,
including the following:</p>
<taglist>
<tag>Process Information</tag>
@@ -195,12 +195,53 @@
</p>
</note>
- <p>Option <em>Trace Processes</em> adds the selected process identifiers to tab
+ <p>Option <em>Trace selected processes</em> adds the selected process identifiers to tab
<em>Trace Overview</em> plus the node that the processes reside on.
</p>
- <p>Option <em>Trace Named Processes</em> adds the registered name of the processes. This can be
+ <p>Option <em>Trace selected processes by name</em> adds the registered name of the processes. This can be
useful when tracing is done on many nodes, as processes with that name are then traced on
all traced nodes.</p>
+ <p>Option <em>Kill process</em> brutally kills the processes under
+ the mouse pointer by sending an exit signal with
+ reason <c>kill</c>.</p>
+
+ </section>
+
+ <section>
+ <title>Ports Tab</title>
+ <p>Tab <em>Ports</em> lists port information in columns.
+ For each port the following information is displayed:
+ </p>
+ <taglist>
+ <tag>Id</tag>
+ <item><p>The port identifier.</p></item>
+ <tag>Connected</tag>
+ <item><p>The process identifier for the process that owns the
+ port.</p></item>
+ <tag>Name</tag>
+ <item><p>The registered name of the port, if any.</p></item>
+ <tag>Controls</tag>
+ <item><p>The name of the command set by <seealso marker="erts:erlang#open_port-2"><c>erlang:open_port/2</c></seealso>.</p></item>
+ <tag>Slot</tag>
+ <item><p>The internal index of the port.</p></item>
+ </taglist>
+
+ <p>Option <em>Port info</em> opens a detailed information window
+ for the port under the mouse pointer. In addition to the
+ information above, it also shows links and monitors.</p>
+
+ <p>Option <em>Trace selected ports</em> adds the selected port
+ identifiers, and the nodes that the ports reside on,
+ to tab <em>Trace Overview</em>.</p>
+
+ <p>Option <em>Trace selected ports by name</em> adds the
+ registered name of the port to tab <em>Trace Overview</em>. This
+ can be useful when tracing is done on many nodes, as ports with
+ that name are then traced on all traced nodes.</p>
+
+ <p>Option <em>Close</em>
+ executes <seealso marker="erts:erlang#port_close-1"><c>erlang:port_close/1</c></seealso>
+ on the port under the mouse pointer.</p>
</section>
@@ -211,8 +252,11 @@
applications are not diplayed. Use menu <em>View</em> to view "system"
ETS tables, unreadable ETS tables, or Mnesia tables.
</p>
- <p>Double-click to view the table content. To view table information, select the table
- and activate menu <em>View &gt; Table information</em>.</p>
+ <p>Double-click to view the table content, or right-click and
+ select option <em>Show Table Content</em>. To view table
+ information, select the table and activate menu <em>View &gt;
+ Table information</em>, or right-click and select option <em>Table
+ info</em>.</p>
<p>You can use <seealso marker="stdlib:re">regular
expressions</seealso> and search for objects, and edit or delete them.
</p>
@@ -220,11 +264,12 @@
<section>
<title>Trace Overview Tab</title>
- <p>Tab <em>Trace Overview</em> handles tracing. Trace
- by selecting the processes to be traced and how to trace
- them. You can trace messages, function calls, and events, where
- events are process-related events such as <c>spawn</c>,
- <c>exit</c>, and many others.
+ <p>Tab <em>Trace Overview</em> handles tracing. Trace by selecting
+ the processes or ports to be traced and how to trace them. For
+ processes, you can trace messages, function calls, scheduling,
+ garbage collections, and process-related events such
+ as <c>spawn</c>, <c>exit</c>, and many others. For ports, you can
+ trace messages, scheduling and port-related events.
</p>
<p>To trace function calls, you also need to set up
@@ -234,27 +279,51 @@
specifications can also be used to trigger more information
in the trace messages.
</p>
- <note><p>Trace patterns only apply to the traced processes.</p></note>
+
+ <p>You can also set match specifications on messages. By default,
+ if tracing messages, all messages sent and/or received by the
+ process or port are traced. Match specifications can be used to
+ reduce the number of traced messages and/or to trigger more
+ information in the trace messages.</p>
+
+ <note><p>Trace patterns only apply to the traced processes and
+ ports.</p></note>
<p>
- Processes are added from the <em>Applications</em> or <em>Processes</em> tabs.
- A special <em>new</em> identifier, meaning all processes spawned after trace
- start, can be added with button <em>Add 'new' Process</em>.
+ Processes are added from the <em>Applications</em>
+ or <em>Processes</em> tabs. Ports are added from
+ the <em>Ports</em> tab. A special <em>new</em> identifier,
+ meaning all processes, or ports, started after trace start, can
+ be added with buttons <em>Add 'new' Processes</em> and <em>Add
+ 'new' Ports</em>, respecively.
</p>
<p>
- When adding processes, a window with trace options is displayed. The chosen
- options are set for the selected processes.
- Process options can be changed by right-clicking a process.
+ When adding processes or ports, a window with trace options is
+ displayed. The chosen options are set for the selected
+ processes/ports. To change the options, right-click the process
+ or port and select <em>Edit process options</em>. To remove a
+ process or port from the list, right-click and select <em>Remove
+ process</em> or <em>Remove port</em>, respectively.
</p>
<p>
- Processes added by process identifiers add the nodes these
- processes reside on in the node list. More nodes can be added by clicking
- button <em>Add Nodes</em>.
+ Processes and ports added by process/port identifiers add the
+ nodes these processes/ports reside on in the node list. More
+ nodes can be added by clicking button <em>Add Nodes</em>, or by
+ right-clicking in the <em>Nodes</em> list and select <em>Add
+ Nodes</em>. To remove nodes, select them, then right-click and
+ choose <em>Remove nodes</em>.
</p>
<p>
If function calls are traced, trace patterns must be added by clicking button
<em>Add Trace Pattern</em>. Select a module, function(s), and a match specification.
- If no functions are selected, all functions in the module are traced.
+ If no functions are selected, all functions in the module are traced.</p>
+ <p>
+ Trace patterns can also be added for traced messages. Click
+ button <em>Add Trace Pattern</em> and select <em>Messages
+ sent</em> or <em>Messages received</em>, and a match
+ specification.
+ </p>
+ <p>
A few basic match specifications are provided in the tool, and
you can provide your own match specifications. The syntax of match
specifications is described in the <seealso
diff --git a/lib/observer/doc/src/ttb.xml b/lib/observer/doc/src/ttb.xml
index 2b637551db..94ecef24b4 100644
--- a/lib/observer/doc/src/ttb.xml
+++ b/lib/observer/doc/src/ttb.xml
@@ -229,27 +229,33 @@ ttb:p(all, call).</input></pre>
</func>
<func>
- <name>p(Procs,Flags) -> Return</name>
- <fsummary>Set the specified trace flags on the specified processes.</fsummary>
+ <name>p(Item,Flags) -> Return</name>
+ <fsummary>Set the specified trace flags on the specified processes or ports.</fsummary>
<type>
- <v>Return = {ok,[{Procs,MatchDesc}]}</v>
- <v>Procs = Process | [Process] | all | new | existing</v>
- <v>Process = pid() | atom() | {global,atom()}</v>
+ <v>Return = {ok,[{Item,MatchDesc}]}</v>
+ <v>Items = Item | [Item]</v>
+ <v>Item = pid() | port() | RegName | {global,GlobalRegName} |
+ all | processes | ports |
+ existing | existing_processes | existing_ports |
+ new | new_processes | new_ports</v>
+ <v>RegName = atom()</v>
+ <v>GlobalRegName = term()</v>
<v>Flags = Flag | [Flag]</v>
</type>
<desc>
- <p>Sets the specified trace flags on the specified
- processes. Flag <c>timestamp</c> is always turned on.
+ <p>Sets the specified trace flags on the specified processes
+ or ports. Flag <c>timestamp</c> is always turned on.
</p>
<p>See the Reference Manual for module
<seealso marker="runtime_tools:dbg"><c>dbg</c></seealso>
- and the possible trace flags. Parameter
+ for the possible trace flags. Parameter
<c>MatchDesc</c> is the same as returned from
<c>dbg:p/2</c>.</p>
<p>Processes can be specified as registered names, globally
- registered names, or process identifiers. If a registered name
- is specified, the flags are set on processes with this name on all
- active nodes.</p>
+ registered names, or process identifiers. Ports can be
+ specified as registered names or port identifiers. If a
+ registered name is specified, the flags are set on
+ processes/ports with this name on all active nodes.</p>
<p>Issuing this command starts the timer for this trace if option
<c>timer</c> is specified with <c>tracer/2</c>.
</p>
@@ -257,17 +263,23 @@ ttb:p(all, call).</input></pre>
</func>
<func>
- <name>tp, tpl, ctp, ctpl, ctpg</name>
+ <name>tp, tpl, tpe, ctp, ctpl, ctpg, ctpe</name>
<fsummary>Set and clear trace patterns.</fsummary>
<desc>
- <p>These functions are to be used with
- trace flag <c>call</c> for setting and clearing trace
- patterns. When trace flag <c>call</c> is set on a process,
+ <p>These functions are to be used with trace
+ flag <c>call</c>, <c>send</c>, and <c>'receive'</c> for
+ setting and clearing trace patterns.</p>
+ <p>When trace flag <c>call</c> is set on a process,
function calls are traced on that process if a trace
- pattern is set for the called function. Trace patterns
- specify how to trace a function by using match
- specifications. Match specifications are described in the
- <seealso marker="erts:users_guide"><c>ERTS User's Guide</c></seealso>.
+ pattern is set for the called function.</p>
+ <p>The <c>send</c> and <c>'receive'</c> flags enable tracing
+ of all messages sent and received by the process/port. Trace
+ patterns set with <c>tpe</c> may limit traced messages based
+ on the message content, the sender, and/or the receiver.</p>
+ <p>Trace patterns specify how to trace a function or a message
+ by using match specifications. Match specifications are
+ described in the
+ <seealso marker="erts:match_spec"><c>ERTS User's Guide</c></seealso>.
</p>
<p>These functions are equivalent to the corresponding
functions in module
@@ -284,6 +296,8 @@ ttb:p(all, call).</input></pre>
<item><p>Sets trace patterns on global function calls.</p></item>
<tag><c>tpl</c></tag>
<item><p>Sets trace patterns on local and global function calls.</p></item>
+ <tag><c>tpe</c></tag>
+ <item><p>Sets trace patterns on messages.</p></item>
<tag><c>ctp</c></tag>
<item><p>Clears trace patterns on local and global function
calls.</p></item>
@@ -291,13 +305,15 @@ ttb:p(all, call).</input></pre>
<item><p>Clears trace patterns on local function calls.</p></item>
<tag><c>ctpg</c></tag>
<item><p>Clears trace patterns on global function calls.</p></item>
+ <tag><c>ctpe</c></tag>
+ <item><p>Clears trace patterns on messages.</p></item>
</taglist>
<p>With <c>tp</c> and <c>tpl</c>, one of the match specification shortcuts
can be used (for example, <c>ttb:tp(foo_module, caller)</c>).</p>
<p>The shortcuts are as follows:</p>
<list type="bulleted">
<item><c>return</c> - for <c>[{'_',[],[{return_trace}]}]</c>
- (report the return value)</item>
+ (report the return value from a traced function)</item>
<item><c>caller</c> - for <c>[{'_',[],[{message,{caller}}]}]</c>
(report the calling function)</item>
<item><c>{codestr, Str}</c> - for <c>dbg:fun2ms/1</c> arguments