<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2011</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
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
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>
<title>Observer</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>observer_ug.xml</file>
</header>
<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>
</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:
</p>
<code>
> erl -sname observer -hidden -setcookie MyCookie -run observer
</code>
<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.
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.
</p>
<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>
</section>
<section>
<title>Applications</title>
<p>The <c>Applications</c> view lists 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.
</p>
</section>
<section>
<title>Processes</title>
<p>The <c>Processes</c> view lists process information.
For each process the following information is presented:
</p>
<taglist>
<tag>Pid</tag>
<item>The process identifier.</item>
<tag>Reds</tag>
<item>This is the number of reductions that has been executed
on the process</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>
<tag>MsgQ</tag>
<item>This is the length of the message queue for the process.</item>
</taglist>
<note>
<p><em>Reds</em> can be presented as accumulated values or as values since last update.</p>
</note>
<p><c>Process info</c> open a detailed information window on the selected process.
<taglist>
<tag>Process Information</tag>
<item>Shows the process information.</item>
<tag>Messages</tag>
<item>Shows the process messages.</item>
<tag>Dictionary</tag>
<item>Shows the process dictionary.</item>
<tag>Stack Trace</tag>
<item>Shows the process current stack trace.</item>
<tag>State</tag>
<item>Show the process state.</item>
<tag>Log</tag>
<item>If enabled and available, show the process SASL log entries.</item>
</taglist>
<note>
<p><c>Log</c> needs SASL application to be started on the observed node, with log_mf_h as log handler.
The Observed node must be R16B02 or higher.
<c>rb</c> server must not be started on the observed node when clicking on menu 'Log/Toggle log view'.
<c>rb</c> server will be stopped on the observed node when exiting or changing observed node.
</p>
</note>
</p>
<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>
</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.
</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.
</p>
<p>In the table viewer you can regexp search for objects, edit and delete objects.
</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
in the trace messages.
</p>
<note><p>Trace patterns only applies to the traced processes.</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.
</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.
</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.
</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>.
</p>
</section>
</chapter>
