aboutsummaryrefslogtreecommitdiffstats
path: root/lib/observer
diff options
context:
space:
mode:
authorSiri Hansen <siri@erlang.org>2016-05-19 15:15:51 +0200
committerSiri Hansen <siri@erlang.org>2016-05-20 09:40:56 +0200
commitab22fe599d0e6918cea46d620acaf7f8e16d36b6 (patch)
treef997ae79823a6428baca70c8304e6b55790eda55 /lib/observer
parent7db703f88a8665bf6fc3266619044da3c882b1e3 (diff)
downloadotp-ab22fe599d0e6918cea46d620acaf7f8e16d36b6.tar.gz
otp-ab22fe599d0e6918cea46d620acaf7f8e16d36b6.tar.bz2
otp-ab22fe599d0e6918cea46d620acaf7f8e16d36b6.zip
[observer] Update user guide
Document the new Ports tab and tracing of ports.
Diffstat (limited to 'lib/observer')
-rw-r--r--lib/observer/doc/src/observer_ug.xml109
1 files changed, 86 insertions, 23 deletions
diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml
index be5d249f37..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,31 +279,49 @@
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.</p>
<p>
- Trace patterns can also be added for traced messages. This is
- done in the same way as for traced function calls. Separate
- trace patterns must be set for sent and received messages.
+ 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