diff options
Diffstat (limited to 'lib/observer/doc')
| -rw-r--r-- | lib/observer/doc/src/observer_ug.xml | 111 | ||||
| -rw-r--r-- | lib/observer/doc/src/ttb.xml | 56 |
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 > 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 > + 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 |