diff options
Diffstat (limited to 'lib/observer/doc/src/observer_ug.xml')
| -rw-r--r-- | lib/observer/doc/src/observer_ug.xml | 393 |
1 files changed, 278 insertions, 115 deletions
diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml index 569d72e71e..6eb72f3e58 100644 --- a/lib/observer/doc/src/observer_ug.xml +++ b/lib/observer/doc/src/observer_ug.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2011</year> + <year>2011</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -31,160 +32,322 @@ <section> <title>Introduction</title> - <p>Observer, is a graphical tool for observing the characteristics of - erlang systems. Observer displays system information, application - supervisor trees, process information, ets or mnesia tables and contains - a frontend for erlang tracing. + <p>Observer is a graphical tool for observing the characteristics of + Erlang systems. Observer displays system information, application + supervisor trees, process information, ETS tables, Mnesia tables + and contains a front end for Erlang tracing. </p> </section> <section> - <title>General</title> - <p>Normally observer should be run from a standalone node to minimize - the impact of the system being observed. Example: + <title>Getting Started</title> + <p>Run Observer from a standalone node to minimize the impact of the + system being observed. </p> - <code> - > erl -sname observer -hidden -setcookie MyCookie -run observer - </code> + <p><em>Example:</em></p> + <pre> +% <input>erl -sname observer -hidden -setcookie MyCookie -run observer</input></pre> <p> - Choose which node to observe via <c>Nodes</c> menu. The <c>View/Refresh - Interval</c> controls how frequent the view should be updated. + Select the node to observe with menu <em>Nodes</em>. + Menu <em>View > Refresh interval</em> controls how often + the view is to be updated. The refresh interval is set per viewer so you can have different settings for each viewer. To minimize the system - impact only the active viewer is updated and the other - views will be updated when activated. + impact, only the active viewer is updated. Other views are updated + when activated. </p> - <note> - <p>Only R15B nodes can be observed.</p> - </note> - <p> In general the mouse buttons behaves as expected, use left click - to select objects, right click to pop up a menu with most used - choices and double click to bring up information about the - selected object. In most viewers with several columns you can change - sort order by left clicking on column header. + <p>The mouse buttons behave as expected. Use left-click + to select objects, right-click to get a menu with the most used + options, and double-click to display information about the + selected object. In most viewers with many columns, you can change + the sort order by left-clicking the column header. </p> </section> <section> - <title>Applications</title> - <p>The <c>Applications</c> view lists application information. + <title>System Tab</title> + <p>Tab <em>System</em> displays general information about the active Erlang node + and its runtime system, such as build configuration, system capabilities, and + overall use statistics. +</p> + </section> + + <section> + <title>Load Charts Tab</title> + <p>Tab <em>Load Charts</em> displays graphs of the current resource use on + the active Erlang node.</p> + <p>Graph <c>Scheduler Utilization</c> shows scheduler use per scheduler, + where each scheduler use has a unique color.</p> + <p>Graph <c>Memory Usage</c> shows the total memory use and per memory category + use, where each category has a unique color. The categories are as + follows:</p> + <taglist> + <tag><c>Total</c></tag> + <item><p>The sum of all memory categories.</p></item> + <tag><c>Processes</c></tag> + <item><p>The sum of all process memory used.</p></item> + <tag><c>Atom</c></tag> + <item><p>The size used by the atom table.</p></item> + <tag><c>Binary</c></tag> + <item><p>The sum of all off-heap binaries allocated.</p></item> + <tag><c>Code</c></tag> + <item><p>The memory allocated for code storage.</p></item> + <tag><c>Ets</c></tag> + <item><p>The used memory for all ETS tables.</p></item> + </taglist> + + <p>Graph <c>IO Usage</c> shows the current I/O load on the system.</p> + </section> + + <section> + <title>Memory Allocators Tab</title> + <p>Tab <em>Memory Allocators</em> displays detailed information of the carrier + size and current memory carriers. For details about memory carriers, + see module + <seealso marker="erts:erts_alloc"><c>erts_alloc</c></seealso> + in application ERTS.</p> + </section> + + <section> + <title>Applications Tab</title> + <p>Tab <em>Applications</em> presents application information. Select an application in the left list to display its supervisor - tree. - </p> - <p><c>Trace process</c> will add the selected process identifier - to <c>Trace Overview</c> view and the node the process resides on - will be added as well. - </p> - <p><c>Trace named process</c> will add the - registered name of the process. This can be useful when tracing on - several nodes, then processes with that name will be traced on all traced - nodes. - </p> - <p><c>Trace process tree</c> and <c>Trace named process - tree</c> will add the selected process and all processes below, - right of, it to the <c>Trace Overview</c> view. + tree. The right-click options in the tree are as follows: </p> + <taglist> + <tag>Process info</tag> + <item><p>Opens a detailed information window on the selected process, + including the following:</p> + <taglist> + <tag>Process Information</tag> + <item><p>Shows the process information.</p></item> + <tag>Messages</tag> + <item><p>Shows the process messages.</p></item> + <tag>Dictionary</tag> + <item><p>Shows the process dictionary.</p></item> + <tag>Stack Trace</tag> + <item><p>Shows the process current stack trace.</p></item> + <tag>State</tag> + <item><p>Shows the process state.</p></item> + <tag>Log</tag> + <item><p>If enabled and available, shows the process SASL + log entries.</p></item> + </taglist> + </item> + <tag>Trace process</tag> + <item><p>Adds the selected process identifier to tab <em>Trace Overview</em> + plus the node that the process resides on.</p></item> + <tag>Trace named process</tag> + <item><p>Adds the registered name of the process. This can be useful when tracing on + many nodes, as processes with that name are then traced on all traced nodes.</p></item> + <tag>Trace process tree</tag> + <item><p>Adds the selected process and all processes below, + right of it, to tab <em>Trace Overview</em>.</p></item> + <tag>Trace named process tree</tag> + <item><p>Adds the selected process and all processes below, + right of it, to tab <em>Trace Overview</em>.</p></item> + </taglist> </section> <section> - <title>Processes</title> - <p>The <c>Processes</c> view lists process information. - For each process the following information is presented: + <title>Processes Tab</title> + <p>Tab <em>Processes</em> lists process information in columns. + For each process the following information is displayed: </p> <taglist> <tag>Pid</tag> - <item>The process identifier.</item> + <item><p>The process identifier.</p></item> <tag>Reds</tag> - <item>This is the number of reductions that has been executed - on the process</item> + <item><p>The number of reductions executed on the process. + This can be presented as accumulated values or as values since the last update.</p></item> <tag>Memory</tag> - <item>This is the size of the process in bytes, obtained by a - call to <c>process_info(Pid,memory)</c>.</item> + <item><p>The size of the process, in bytes, obtained by a + call to <c>process_info(Pid,memory)</c>.</p></item> <tag>MsgQ</tag> - <item>This is the length of the message queue for the process.</item> + <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 process under the mouse pointer, + including the following:</p> + <taglist> + <tag>Process Information</tag> + <item><p>Shows the process information.</p></item> + <tag>Messages</tag> + <item><p>Shows the process messages.</p></item> + <tag>Dictionary</tag> + <item><p>Shows the process dictionary.</p></item> + <tag>Stack Trace</tag> + <item><p>Shows the process current stack trace.</p></item> + <tag>State</tag> + <item><p>Shows the process state.</p></item> + <tag>Log</tag> + <item><p>If enabled and available, shows the process SASL log entries.</p></item> </taglist> + <note> - <p><em>Reds</em> can be presented as accumulated values or as values since last update.</p> + <p><em>Log</em> requires application SASL to be started on the observed node, + with <c>log_mf_h</c> as log handler. + The Observed node must be Erlang/OTP R16B02 or higher. + The <c>rb</c> server must not be started on the observed node when clicking menu + <em>Log > Toggle log view</em>. The <c>rb</c> server is stopped on the observed node + when exiting or changing the observed node. + </p> </note> - <p><c>Trace Processes</c> will add the selected process identifiers to the <c>Trace Overview</c> view and the - node the processes reside on will be added as well. - <c>Trace Named Processes</c> will add the registered name of processes. This can be useful - when tracing is done on several nodes, then processes with that name will be traced on all traced nodes. + + <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 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>Table Viewer</title> - <p>The <c>Table Viewer</c> view lists tables. By default ets tables - are visible and unreadable, private ets, tables and tables created by the OTP - applications are not visible. Use <c>View</c> menu to view "system" - ets tables, unreadable ets tables or mnesia tables. + <title>Ports Tab</title> + <p>Tab <em>Ports</em> lists port information in columns. + For each port the following information is displayed: </p> - <p>Double click to view the content of the table. Select table and activate <c>View/Table Information</c> - menu to view table information. + <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> + + <section> + <title>Table Viewer Tab</title> + <p>Tab <em>Table Viewer</em> lists tables. By default, ETS tables + are displayed whereas unreadable private ETS tables and tables created by OTP + applications are not diplayed. Use menu <em>View</em> to view "system" + ETS tables, unreadable ETS tables, or Mnesia tables. </p> - <p>In the table viewer you can regexp search for objects, edit and delete objects. + <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> </section> <section> - <title>Trace Overview</title> - <p>The <c>Trace Overview</c> view handles tracing. Tracing is done - by selecting which 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 several others. - </p> - - <p>When you want to trace function calls, you also need to setup - <c>trace patterns</c>. Trace patterns selects the function calls - that will be traced. The number of traced function calls can be - further reduced with <c>match specifications</c>. Match - specifications can also be used to trigger additional information + <title>Trace Overview Tab</title> + <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 + <em>trace patterns</em>. Trace patterns select the function calls + to be traced. The number of traced function calls can be + further reduced with <em>match specifications</em>. Match + specifications can also be used to trigger more information in the trace messages. </p> - <note><p>Trace patterns only applies 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 <c>Applications</c> or <c>Processes</c> views. - A special <c>new</c> identifier, meaning all processes spawned after trace start, - can be added with the <c>Add 'new' Process</c> button. + 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 will pop up. The chosen options will - be set for the selected processes. - Process options can be changed by right clicking on 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 will add the nodes these - processes resides on in the node list. Additional nodes can be added by the <c>Add - Nodes</c> button. + 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. Click + button <em>Add Trace Pattern</em> and select <em>Messages + sent</em> or <em>Messages received</em>, and a match + specification. </p> <p> - If function calls are traced, trace patterns must be added by <c>Add Trace Pattern</c> button. - Select a module, function(s) and a match specification. - If no functions are selected, all functions in the module will be traced. A few basic match specifications are provided in the tool, and you can provide your own match specifications. The syntax of match - specifications are described in the <seealso - marker="erts:match_spec">ERTS User's Guide</seealso>. To simplify - the writing of a match specification they can also be written as - <c>fun/1</c> see <seealso marker="stdlib:ms_transform">ms_transform manual page</seealso> for - further information. - </p> - - <p>Use the <c>Start trace</c> button to start the trace. - By default trace output is written to a new window, tracing is stopped when the - window is closed, or with <c>Stop Trace</c> button. - Trace output can be changed via <c>Options/Output</c> menu. - The trace settings, including match specifications, can be saved to, or loaded from, a file. - </p> - <p>More information about tracing can be found in <seealso - marker="runtime_tools:dbg">dbg</seealso> and in the chapter "Match - specifications in Erlang" in <seealso marker="erts:match_spec">ERTS User's - Guide</seealso> and the - <seealso marker="stdlib:ms_transform">ms_transform manual page</seealso>. + specifications is described in the <seealso + marker="erts:match_spec"><c>ERTS User's Guide</c></seealso>. To simplify + the writing of a match specification, they can also be written as + <c>fun/1</c>. For details, see module + <seealso marker="stdlib:ms_transform">ms_transform</seealso> + in application STDLIB. + </p> + + <p>Click button <em>Start Trace</em> to start the trace. + By default, trace output is written to a new window. Tracing is stopped + when the window is closed, or when clicking button <em>Stop Trace</em>. + Trace output can be changed with menu <em>Options > Output</em>. + The trace settings, including match specifications, can be saved to, + or loaded from, a file. + </p> + <p>For details about tracing, see module <seealso + marker="runtime_tools:dbg">dbg</seealso> in application Runtime_Tools + and in section "Match specifications in Erlang" in + <seealso marker="erts:match_spec"><c>ERTS User's Guide</c></seealso> + and in module + <seealso marker="stdlib:ms_transform"><c>ms_transform</c></seealso> + in application STDLIB. </p> </section> </chapter> |