diff options
Diffstat (limited to 'lib/observer/doc/src')
| -rw-r--r-- | lib/observer/doc/src/Makefile | 20 | ||||
| -rw-r--r-- | lib/observer/doc/src/etop.xml | 33 | ||||
| -rw-r--r-- | lib/observer/doc/src/make.dep | 29 | ||||
| -rw-r--r-- | lib/observer/doc/src/notes.xml | 119 | ||||
| -rw-r--r-- | lib/observer/doc/src/observer.xml | 58 | ||||
| -rw-r--r-- | lib/observer/doc/src/observer_ug.xml | 190 | ||||
| -rw-r--r-- | lib/observer/doc/src/part.xml | 3 | ||||
| -rw-r--r-- | lib/observer/doc/src/ref_man.xml | 3 | ||||
| -rw-r--r-- | lib/observer/doc/src/ttb_ug.xml | 2 |
9 files changed, 415 insertions, 42 deletions
diff --git a/lib/observer/doc/src/Makefile b/lib/observer/doc/src/Makefile index f82a49abbe..0f564d3299 100644 --- a/lib/observer/doc/src/Makefile +++ b/lib/observer/doc/src/Makefile @@ -36,6 +36,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) XML_APPLICATION_FILES = ref_man.xml XML_REF3_FILES = \ crashdump.xml \ + observer.xml \ etop.xml \ ttb.xml XML_REF6_FILES = observer_app.xml @@ -48,6 +49,7 @@ XML_PART_FILES = \ XML_CHAPTER_FILES = \ crashdump_ug.xml \ etop_ug.xml \ + observer_ug.xml \ ttb_ug.xml \ notes.xml \ notes_history.xml @@ -131,16 +133,16 @@ include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs - $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf - $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf - $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(HTMLDIR)/* \ - $(RELSYSDIR)/doc/html - $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) - $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 - $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 - $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 - $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6 + "$(RELSYSDIR)/doc/html" + $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" + $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man6" + $(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6" release_spec: diff --git a/lib/observer/doc/src/etop.xml b/lib/observer/doc/src/etop.xml index 78047caab3..af6bb2442b 100644 --- a/lib/observer/doc/src/etop.xml +++ b/lib/observer/doc/src/etop.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2002</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -114,6 +114,37 @@ Default: <c>on</c></item> </description> <funcs> <func> + <name>start() -> ok</name> + <fsummary>Start etop</fsummary> + <desc> + <p>This function starts <c>etop</c>. + Note that etop is preferably started with the etop and getop scripts</p> + </desc> + </func> + <func> + <name>start(Options) -> ok</name> + <fsummary>Start etop</fsummary> + <type> + <v>Options = [Option]</v> + <v>Option = {Key, Value}</v> + <v>Key = atom()</v> + <v>Value = term()</v> + </type> + <desc> + <p>This function starts <c>etop</c>. Use + <seealso marker="#help/0">help/0</seealso> to see a + description of the possible options.</p> + </desc> + </func> + <func> + <name>help() -> ok</name> + <fsummary>Print etop's help</fsummary> + <desc> + <p>This function prints the help of <c>etop</c> and + its options.</p> + </desc> + </func> + <func> <name>config(Key,Value) -> Result</name> <fsummary>Change tool's configuration</fsummary> <type> diff --git a/lib/observer/doc/src/make.dep b/lib/observer/doc/src/make.dep deleted file mode 100644 index 3c1b3df771..0000000000 --- a/lib/observer/doc/src/make.dep +++ /dev/null @@ -1,29 +0,0 @@ -# ---------------------------------------------------- -# >>>> Do not edit this file <<<< -# This file was automaticly generated by -# /home/otp/bin/docdepend -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# TeX files that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: book.tex crashdump.tex crashdump_ug.tex etop.tex \ - etop_ug.tex observer_app.tex part.tex ref_man.tex \ - ttb.tex ttb_ug.tex - -# ---------------------------------------------------- -# Source inlined when transforming from source to LaTeX -# ---------------------------------------------------- - -book.tex: ref_man.xml - -# ---------------------------------------------------- -# Pictures that the DVI file depend on -# ---------------------------------------------------- - -book.dvi: etop_5.ps etop_lines.ps etop_main.ps etop_opt.ps - -book.dvi: et_modsprocs.ps et_processes.ps - diff --git a/lib/observer/doc/src/notes.xml b/lib/observer/doc/src/notes.xml index baa1354268..a9554a08f4 100644 --- a/lib/observer/doc/src/notes.xml +++ b/lib/observer/doc/src/notes.xml @@ -31,6 +31,125 @@ <p>This document describes the changes made to the Observer application.</p> +<section><title>Observer 1.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The following bugs in <c>ttb</c> have been corrected:</p> + <p> + <list> <item><c>ttb:tracer/2</c> would earlier crash when + trying to set up tracing for a diskless node to wrap + files, i.e. when option + <c>{file,{local,{wrap,Filename,Size,Count}}}</c> was + used.</item> <item><c>ttb:stop([fetch])</c> would + sometimes silently fail if multiple nodes with different + current working directories were traced.</item> + <item><c>ttb:stop([fetch])</c> would crash if the tracer + was started with option + <c>{file,{local,Filename}}</c></item> <item>A deadlock + would sometimes occur due to an information printout from + the <c>ttb_control</c> process when <c>ttb</c> was + stopped.</item> </list></p> + <p> + Own Id: OTP-9431</p> + </item> + <item> + <p> + The file trace port to which the IP trace client relays + all traces from diskless nodes was not flushed and closed + properly on ttb:stop. This has been corrected.</p> + <p> + Own Id: OTP-9665</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new GUI for Observer. Integrating pman, etop, appmon + and tv into observer with tracing facilities.</p> + <p> + Own Id: OTP-4779</p> + </item> + <item> + <p> + The following new features are added to <c>ttb</c>:</p> + <p> + <list> <item>A one-command trace setup is added, + <c>ttb:start_trace/4</c>.</item> <item>The following new + options are added to <c>ttb:tracer/2</c>: <list> + <item><em><c>shell</c></em> - Show trace messages on the + console in real time</item> <item><em><c>timer</c></em> - + Time constrained tracing</item> + <item><em><c>overload</c></em> - Overload + protection</item> <item><em><c>flush</c></em> - Flush + file trace port buffers with given frequency</item> + <item><em><c>resume</c></em> - Automatically resume + tracing after node restart</item> </list> </item> <item> + A new shortcut is added for common tracer settings + similar to using the <c>dbg</c> module directly, + <c>ttb:tracer(shell | dbg)</c>. </item> <item> Some + shortcuts are added for commonly used match + specifications in <c>ttb:tp</c> and <c>ttb:tpl</c>. + </item> <item> The <c>Options</c> argument to functions + <c>ttb:tracer</c>, <c>ttb:write_config</c>, + <c>ttb:stop</c> and <c>ttb:format</c> may now be one + single option instead of a list. </item> <item> The + history buffer of the last trace is now always + automatically dumped to the file <c>ttb_last_config</c> + when <c>ttb:stop</c> is called. </item> <item> The + following new options are added to <c>ttb:stop/1</c>: + <list> <item><em><c>fetch_dir</c></em> - Specify where to + store fetched logs</item> + <item><em><c>{format,FormatOpts}</c></em> - Specify + options to use when formatting the fetched logs</item> + <item><em><c>return_fetch_dir</c></em> - Indicate that + the return value from <c>ttb:stop/1</c> should include + the name of the directory where the fetched logs are + stored</item> </list> </item> <item> The option + <c>disable_sort</c> is added to <c>ttb:format/2</c>. When + this option is used, trace messages from different logs + are not merged according to timestamps, but just appended + one log after the other. </item> </list></p> + <p> + Own Id: OTP-9403</p> + </item> + <item> + <p> + The following non backwards compatible changes are done + in <c>ttb</c>:</p> + <p> + <list> <item> When setting up trace with ttb, the + 'timestamp' trace flag will now always be set. </item> + <item> The 'fetch' option to ttb:stop/1 is removed since + it is now default behavior that trace logs are fetched + when stopping ttb. Fetching can be disabled with the + 'nofetch' option to ttb:stop/1. </item> <item> The name + of the upload directory is changed from + ttb_upload-Timestamp to ttb_upload_FileName-Timestamp. + </item> <item> To format the output using 'et', you now + need to provide the option {handler,ttb:get_et_handler()} + instead of {handler,et}. </item> <item> When formatting a + trace log, the handler state was earlier reset after each + trace file, this is now changed so the handler state is + passed not only from one trace message to the next in the + same file, but also from one file to the next. </item> + </list></p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-9430</p> + </item> + </list> + </section> + +</section> + <section><title>Observer 0.9.10</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/observer/doc/src/observer.xml b/lib/observer/doc/src/observer.xml new file mode 100644 index 0000000000..03830f2b1c --- /dev/null +++ b/lib/observer/doc/src/observer.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2011</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/. + + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Observer</title> + <prepared>Dan Gudmundsson</prepared> + <responsible></responsible> + <docno>1</docno> + <approved></approved> + <checked></checked> + <date>2011-12-08</date> + <rev>PA1</rev> + <file>observer.xml</file> + </header> + <module>observer</module> + <modulesummary>A GUI tool for observing an erlang system.</modulesummary> + <description> + <p>The observer is gui frontend containing various tools to + inspect a system. It displays system information, application + structures, process information, ets or mnesia tables and a frontend + for tracing with <seealso marker="ttb">ttb</seealso>. + </p> + + <p>See the <seealso marker="observer_ug">user's guide</seealso> + for more information about how to get started.</p> + </description> + <funcs> + <func> + <name>start() -> ok</name> + <fsummary>Start the observer gui</fsummary> + <desc> + <p>This function starts the <c>observer</c> gui. + Close the window to stop the application. + </p> + </desc> + </func> + </funcs> +</erlref> diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml new file mode 100644 index 0000000000..569d72e71e --- /dev/null +++ b/lib/observer/doc/src/observer_ug.xml @@ -0,0 +1,190 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2011</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/. + + 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. + + </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> + <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> + </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>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> diff --git a/lib/observer/doc/src/part.xml b/lib/observer/doc/src/part.xml index bd6c2b6c77..0d6aad09f2 100644 --- a/lib/observer/doc/src/part.xml +++ b/lib/observer/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2002</year><year>2009</year> + <year>2002</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,7 @@ <p>The <em>Observer</em> application contains tools for tracing and investigation of distributed systems.</p> </description> + <xi:include href="observer_ug.xml"/> <xi:include href="ttb_ug.xml"/> <xi:include href="etop_ug.xml"/> <xi:include href="crashdump_ug.xml"/> diff --git a/lib/observer/doc/src/ref_man.xml b/lib/observer/doc/src/ref_man.xml index 3d37570d2d..c33ce74141 100644 --- a/lib/observer/doc/src/ref_man.xml +++ b/lib/observer/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2002</year><year>2009</year> + <year>2002</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,6 +34,7 @@ <br></br> </description> <xi:include href="observer_app.xml"/> + <xi:include href="observer.xml"/> <xi:include href="ttb.xml"/> <xi:include href="etop.xml"/> <xi:include href="crashdump.xml"/> diff --git a/lib/observer/doc/src/ttb_ug.xml b/lib/observer/doc/src/ttb_ug.xml index 4f2b55a22a..08093a9451 100644 --- a/lib/observer/doc/src/ttb_ug.xml +++ b/lib/observer/doc/src/ttb_ug.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2002</year><year>2010</year> + <year>2002</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> |