From e6b2edc8027c40db4c12f8f081648cda4634f9f7 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Mon, 23 Nov 2015 18:27:25 +0100 Subject: Observer: Editorial changes in documentation --- lib/observer/doc/src/cdv.xml | 14 +- lib/observer/doc/src/crashdump.xml | 21 +- lib/observer/doc/src/crashdump_ug.xml | 437 +++++++------ lib/observer/doc/src/etop.xml | 137 ++-- lib/observer/doc/src/etop_ug.xml | 118 ++-- lib/observer/doc/src/introduction_ug.xml | 49 ++ lib/observer/doc/src/observer.xml | 23 +- lib/observer/doc/src/observer_app.xml | 20 +- lib/observer/doc/src/observer_ug.xml | 306 +++++---- lib/observer/doc/src/part.xml | 3 +- lib/observer/doc/src/ref_man.xml | 5 +- lib/observer/doc/src/ttb.xml | 515 ++++++++------- lib/observer/doc/src/ttb_ug.xml | 1032 ++++++++++++++++-------------- 13 files changed, 1455 insertions(+), 1225 deletions(-) create mode 100644 lib/observer/doc/src/introduction_ug.xml diff --git a/lib/observer/doc/src/cdv.xml b/lib/observer/doc/src/cdv.xml index ee629bbd3f..df1032780a 100644 --- a/lib/observer/doc/src/cdv.xml +++ b/lib/observer/doc/src/cdv.xml @@ -4,7 +4,7 @@
- 2013 + 20032016 Ericsson AB. All Rights Reserved. @@ -33,16 +33,16 @@ cdv.xml
cdv - Script used for starting the Crashdump Viewer from the + Script to start the Crashdump Viewer from the OS command line. -

The cdv shell script can be found under the priv - directory of the observer application. The script is used +

The cdv shell script is located in directory priv + of the Observer application. The script is used for starting the Crashdump Viewer tool from the OS command line.

-

For Windows users, cdv.bat can be found in the same +

For Windows users, cdv.bat is found in the same location.

 @@ -51,8 +51,8 @@ cdv [file] Start the Crashdump Viewer and load the given file. -

The file arguments is optional. If not given, a file - dialog will pop up allowing the user to select a crashdump +

Argument file is optional. If not specified, a file + dialog is displayed, allowing you to select a crashdump from the file system.

 diff --git a/lib/observer/doc/src/crashdump.xml b/lib/observer/doc/src/crashdump.xml index 76deee45f6..27e88d07e5 100644 --- a/lib/observer/doc/src/crashdump.xml +++ b/lib/observer/doc/src/crashdump.xml @@ -25,7 +25,7 @@ crashdump_viewer - Siri hansen + Siri Hansen 1 @@ -41,32 +41,31 @@

The Crashdump Viewer is a WxWidgets based tool for browsing Erlang crashdumps.

-

See the user's guide - for more information about how to get started with the Crashdump - Viewer.

+

For details about how to get started with the Crashdump Viewer, see the + User's Guide.

start() -> ok start(File) -> ok - Start the crashdump_viewer + Start the Crashdump Viewer. File = string() - The file name of the crashdump. + The filename of the crashdump. -

This function starts the crashdump_viewer GUI and - loads the given crashdump.

+

Starts the Crashdump Viewer GUI and + loads the specified crashdump.

-

If File is not given, a file dialog will be opened +

If File is not specified, a file dialog is opened where the crashdump can be selected.

 stop() -> ok - Stop the crashdump_viewer + Terminate the Crashdump Viewer. -

This function stops the crashdump_viewer and closes +

Terminates the Crashdump Viewer and closes all GUI windows.

 diff --git a/lib/observer/doc/src/crashdump_ug.xml b/lib/observer/doc/src/crashdump_ug.xml index 4bb3628ab5..4ba057c3fb 100644 --- a/lib/observer/doc/src/crashdump_ug.xml +++ b/lib/observer/doc/src/crashdump_ug.xml @@ -4,7 +4,7 @@
- 20032013 + 20032016 Ericsson AB. All Rights Reserved. @@ -39,371 +39,390 @@
Getting Started -

The easiest way to start Crashdump Viewer is to use the - provided shell script named cdv with the full path to the - erlang crashdump as an argument. The script can be found in the - priv directory of the observer application. This starts the - Crashdump Viewer GUI and loads the given file. If no file name is - given, a file dialog will be opened where the file can be +

The easiest way to start Crashdump Viewer is to use + shell script cdv with the full path to the + Erlang crashdump as argument. The script is located in + directory priv of the Observer application. This starts the + Crashdump Viewer GUI and loads the specified file. If no filename is + specified, a file dialog is opened where the file can be selected.

-

Under Windows the batch file cdv.bat can be used.

+

Under Windows, the batch file cdv.bat can be used.

-

It is also possible to start the Crashdump Viewer from within - an erlang node by calling Crashdump Viewer can also be started from + an Erlang node by calling crashdump_viewer:start/0 or crashdump_viewer:start/1.

- The graphical interface + GUI -

The main window is opened when Crashdump Viewer has loaded a - crashdump. It contains a title bar, a menu bar, a number of - information panels and a status bar.

+

The GUI main window is opened when Crashdump Viewer has loaded a + crashdump. It contains a title bar, a menu bar, + information tabs, and a status bar.

The title bar shows the name of the currently loaded crashdump.

The menu bar contains a File menu and a Help - menu. From the File menu a new crashdump can be loaded or the tool - can be terminated. From the Help menu this user's guide and the - chapter "How to interpret the Erlang crash dumps" from the user's - guide for Erlang runtime system can be opened. "How to interpret + menu. From the File menu, a new crashdump can be loaded or + the tool can be terminated. From the Help menu, this User's Guide + and section "How to interpret the Erlang crash dumps" from the + ERTS application can be opened. "How to interpret the Erlang crash dumps" describes the raw crashdumps in - detail. Here you will also find information about each single - field in the different information pages. This document can also - be found directly in the OTP online documentation, via the Erlang - runtime system user's guide.

+ detail and includes information about each + field in the information pages."How to interpret the Erlang crash dumps" + is also available in the OTP online documentation.

-

The status bar at the bottom of the window will show a warning +

The status bar at the bottom of the window shows a warning if the currently loaded dump is truncated.

-

The centre area of the main window contains the information - panels. Each panel displays information about a specific item or a - list of items. A panel is selected by clicking the title of the - tab.

+

The center area of the main window contains the information + tabs. Each tab displays information about a specific item or a + list of items. Select a tab by clicking the tab title.

-

From panels that display lists of items, for example the - Processes- or the Ports panel, a new window with further - information can be opened by double clicking a row or by right - clicking the row and selecting an item from the drop down +

From tabs displaying lists of items, for example, the + Processes tab or the Ports tab, a new window with + more information can be opened by double-clicking a row or by right- + clicking the row and selecting an item from the drop-down menu. The new window is called a detail window. Detail windows can - be opened for processes, ports, nodes and modules.

+ be opened for processes, ports, nodes, and modules.

-

The various information shown in a detail window might contain - links to processes or ports. Clicking one of these links will open +

The information shown in a detail window can contain + links to processes or ports. Clicking one of these links opens the detail window for the process or port in question. If the - process or port resided on a remote node, there will be no - information available. Clicking the link will then pop up a dialog - where you can choose whether to open the detail window for the - remote node or not. + process or port resides on a remote node, no + information is available. Clicking the link then displays a dialog + where you can choose to open the detail window for the + remote node.

-

Some of the panels contain a left hand menu where sub items of - the panel's information area can be selected. Click on one of the - rows, and the information will be displayed in the right hand +

Some tabs contain a left-hand menu where subitems of + the information area can be selected. Click one of the + rows, and the information is displayed in the right-hand information area.

- Data content - -

Each panel in the main window contains an information - page. If no information is found for an item, the page will be - empty. The reason for not finding any information about an item - can be that the dump is truncated, that it is a dump from an old - OTP release in which this item was not written or that the item - simply wasn't present in the system at the point of failure.

- -

If the dump was truncated, a warning is displayed in the - status bar of the main window.

- -

Even if some information about an item exists, there might be + Tab Content + +

Each tab in the main window contains an information + page. If no information is found for an item, the page is + empty. The reason for not finding information about an item + can be the following:

+ + It is a dump from an old OTP release in which this item was not written. + The item was not present in the system at the point of failure. + The dump is truncated. In this case, a warning is displayed in the + status bar of the main window. + + +

+ +

Even if some information about an item exists, there can be empty fields if the dump originates from an old OTP release.

-

The value "-1" in any field means "unknown", and in most +

The value -1 in any field means "unknown", and in most cases it means that the dump was truncated somewhere around this field.

-

The sections below describe some of the fields in the - different information panels. These are fields that do not exist +

The following sections describe some of the fields in the + information tabs. These are fields that do not exist in the raw crashdump, or in some way differ from the fields in - the raw crashdump. Details about other fields can be found in - the user's guide for the Erlang runtime system, in the chapter - "How to interpret the Erlang crash dumps". That chapter can also - be opened from the Help menu in the Crashdump Viewer's main - window, and there are also direct links from the specific - sections below to related information in "How to interpret the - Erlang crash dumps".

+ the raw crashdump. For details about other fields, see + the + ERTS User's Guide, section + "How to interpret the Erlang crash dumps". That section can also + be opened from the Help menu in the main window. + There are also links from the following sections to related information + in "How to interpret the Erlang crash dumps".

- General information + General Tab -

The General information panel shows a short overview +

Tab General shows a short overview of the dump.

-

The following fields are not described in the Erlang runtime - system user's guide:

+

The following fields are not described in the ERTS + User's Guide:

- Crashdump created on - Time of failure. - - Memory allocated - The total number of bytes allocated, equivalent to - c:memory(total). - - Memory maximum - The maximum number of bytes that has been allocated during - the lifetime of the originating node. This will only be shown if - the Erlang runtime system was run instrumented. - - Atoms - If available in the dump, this is the total number of - atoms in the atom table. If the size of the atom table is not - available, the number of atoms visible in the dump is - presented. - - Processes, ETS tables and Funs - The number of processes, ETS tables and funs visible in - the dump. + Crashdump created on +

Time of failure.

 + + Memory allocated +

The total number of bytes allocated, equivalent to + c:memory(total).

 + + Memory maximum +

The maximum number of bytes that has been allocated during + the lifetime of the originating node. This is only shown if + the Erlang runtime system is run instrumented.

 + + Atoms +

If available in the dump, this is the total number of + atoms in the atom table. If the size of the atom table is + unavailable, the number of atoms visible in the dump is + displayed.

 + + Processes +

The number of processes visible in the dump.

 + + ETS tables +

The number of ETS tables visible in the dump.

 + + Funs +

The number of funs visible in the dump.

 -

- More... +

For details, see + General Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Processes + Processes Tab -

The Processes panel shows a list of all processes - found in the crashdump, including some short information about - each process. By default the processes are sorted by their - pids. To sort by other topic, click the desired column - heading.

+

Tab Processes shows a list of all processes + found in the crashdump, including brief information about + each process. By default, the processes are sorted by their + pids. To sort by another topic, click the desired column heading.

-

The Memory column shows the 'Memory' field which was - added to crashdumps in R16B01. This is the total amount of memory +

Column Memory shows the 'Memory' field that was + added to crashdumps in Erlang/OTP R16B01. This is the total amount of memory used by the process. For crashdumps from earlier releases, this - column shows the 'Stack+heap' field. The value shown is always in - bytes.

+ column shows the 'Stack+heap' field. The value is always in bytes.

-

To view detailed information about a specific process, double - click the row in the list or right click the row and select - "Properties for <pid>".

+

To view detailed information about a specific process, double- + click the row in the list, or right-click the row and select + Properties for <pid>.

-

- More... +

For details, see + Process Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Ports + Ports Tab -

The Ports panel is similar to the Processes - panel, except it lists all ports found in the crashdump.

+

Tab Ports is similar to the Processes + tab, except it lists all ports found in the crashdump.

-

To see more details about a specific port, dobule click the row - or right click it and select "Properties for <port>". From - the right click menu you can also select "Properties for - <pid>", where <pid> is the process connected to the +

To view more details about a specific port, double-click the row + or right-click it and select Properties for <port>. From + the right-click menu, you can also select Properties for + <pid>, where <pid> is the process connected to the port.

-

- - More... +

For details, see + Port Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- ETS tables + ETS Tables Tab -

The ETS Tables panel shows all ETS table information - found in the dump. The 'Id' is the same as the 'Table' field found - in the raw crashdump, and 'Memory' is the 'Words' field from the - raw crashdump translated into bytes. For tree tables there will - be no value in the 'Objects' field.

+

Tab ETS Tables shows all ETS table information + found in the dump. Id is the same as the 'Table' field + in the raw crashdump. Memory is the 'Words' field from the + raw crashdump translated into bytes. For tree tables, there is + no value in the 'Objects' field.

-

To open the detailed information page about the table, double - click or right click the row and select "Properties for - 'Identifier'".

+

To open the detailed information page about the table, double- + click, or right-click the row and select Properties for + 'Identifier'.

To open the detailed information page about the owner process - of an ETS table, right click the row and select "Properties for - <pid>".

+ of an ETS table, right-click the row and select Properties for + <pid>.

-

- - More... +

For details, see + ETS Tables + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Timers + Timers Tab -

The Timers panel shows all timer information found in +

Tab Timers shows all timer information found in the dump.

To open the detailed information page about the owner process - of a timer, right click the row and select "Properties for - <pid>".

+ of a timer, right-click the row and select Properties for + <pid>.

-

Double clicking a row in the Timers panel has no effect.

+

Double-clicking a row in the Timers tab has no effect.

-

- More... +

For details, see + Timers + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Schedulers + Schedulers Tab -

The Schedulers panel shows all scheduler information +

Tab Schedulers shows all scheduler information found in the dump.

To open the detailed information page about the scheduler, - double click or right click the row and select "Properties for - 'Identifier'".

+ double-click, or right-click the row and select Properties for + 'Identifier'.

-

- More... +

For details, see + Scheduler Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Funs + Funs Tab -

The Funs panel shows all Fun information found in the +

Tab Funs shows all fun information found in the dump.

To open the detailed information page about the module to which - the fun belongs, right click the row and select "Properties for - <mod>".

+ the fun belongs, right-click the row and select Properties for + <mod>.

-

Double clicking a row in the Funs panel has no effect.

+

Double-clicking a row in the Funs tab has no effect.

-

- More... +

For details, see + Fun Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Atoms + Atoms Tab -

The Atoms panel lists all atoms found in the dump. By +

Tab Atoms lists all atoms found in the dump. By default the atoms are sorted in creation order from first to last. This is opposite of the raw crashdump where atoms are listed from last to first, meaning that if the dump was truncated in the - middle of the atom list only the last created atoms will be seen - in the Atoms panel.

+ middle of the atom list, only the last created atoms are visible + in the Atoms tab.

-

- More... +

For details, see + Atoms + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Nodes + Nodes Tab -

The Nodes panel shows a list of all external erlang - nodes which are referenced from the crashdump.

+

Tab Nodes shows a list of all external Erlang + nodes that are referenced from the crashdump.

-

If the page is empty it either means that the crashed node was - not distributed, that it was distributed but had no references to - other nodes or that the dump was truncated.

+

If the page is empty, it means either of the following:

+ + The crashed node is not distributed. + The crashed node is distributed but has no references to other nodes. + The dump is truncated. + -

If the node was distributed, all referenced nodes are - shown. The column named Connection type shows if the node - is visible, hidden or not connected. Visible nodes are alive nodes +

If the node is distributed, all referenced nodes are + visible. Column Connection type shows if the node + is visible, hidden, or not connected. Visible nodes are alive nodes with a living connection to the originating node. Hidden nodes are - the same as visible nodes, except they are started with the - -hidden flag. Not connected nodes are nodes that are not + the same as visible nodes, except they are started with flag + -hidden. Not connected nodes are nodes that are not connected to the originating node anymore, but references - (i.e. process or port identifiers) exist.

+ (that is, process or port identifiers) exist.

-

To see more detailed information about a node, double click the - row or right click the row and select "Properties for node - <node>". From the right click menu you can also select - "Properties for <port>", to open the detailed information +

To see more detailed information about a node, double-click the + row, or right-click the row and select Properties for node + <node>. From the right-click menu, you can also select + Properties for <port>, to open the detailed information window for the controlling port.

-

In the detailed information window for a node, any exsisting +

In the detailed information window for a node, any existing links and monitors between processes on the originating node and - the connected node are shown. Extra Info may contain - debug information (i.e. special information written if the - emulator is debug compiled) or error information.

+ the connected node are displayed. Extra Info can contain + debug information (that is, special information written if the + emulator is debug-compiled) or error information.

-

- - More... +

For details, see + Distribution Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Loaded modules + Modules Tab -

The Modules panel lists all modules that were loaded - on the originating node, and the current size of the code. If old - code exsits, the old size is also shown.

+

Tab Modules lists all modules loaded + on the originating node, and the current code size. If old + code exists, the old size is also shown.

-

To see detailed information about a specific module, double - click the row or right click it and select "Properties for - <mod>".

+

To view detailed information about a specific module, double- + click the row, or right-click it and select Properties for + <mod>.

-

- - More... +

For details, see + Loaded Module Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

- Memory - -

The Memory panel shows memory and allocator - information. From the left hand menu you can select:

+ Memory Tab - +

Tab Memory shows memory and allocator + information. From the left-hand menu you can select the following:

- Memory More... + + Memory +

See + Memory Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

 - Allocator Summary - this page presents a - summary of values from all allocators below. + Allocator Summary +

This page presents a summary of values from all allocators underneath it.

 - <Allocator> - one entry per allocator - More... + <Allocator> +

One entry per allocator. See + Allocator + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

 - Allocated Areas More... + Allocated Areas +

See + Allocated Areas + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

 - +
- Internal tables + Internal Tables Tab -

On the Internal Tables panel you can choose from the - left hand menu to see hash tables or index tables.

+

On tab Internal Tables you can from the + left-hand menu select Hash Tables, Index Tables, + or Internal ETS Tables.

-

- More... +

For details, see + Internal Table Information + in section "How to Interpret the Erlang Crash Dumps" in ERTS.

diff --git a/lib/observer/doc/src/etop.xml b/lib/observer/doc/src/etop.xml index c1e336177f..52f3b2a156 100644 --- a/lib/observer/doc/src/etop.xml +++ b/lib/observer/doc/src/etop.xml @@ -25,7 +25,7 @@ etop - Siri hansen + Siri Hansen @@ -35,89 +35,79 @@
etop - Erlang Top is a tool for presenting information about erlang processes similar to the information presented by "top" in UNIX. + Erlang Top is a tool for presenting information about Erlang + processes similar to the information presented by "top" in UNIX. -

etop should be started with the provided scripts - etop. This will start a hidden erlang node - which connects to the node to be measured. The measured node is - given with the -node option. If the measured node has a +

Start Erlang Top with the provided scripts + etop. This starts a hidden Erlang node + that connects to the node to be measured. The measured node is + specified with option -node. If the measured node has a different cookie than the default cookie for the user who - invokes the script, the cookie must be explicitly given witht - the -setcookie option.

+ invokes the script, the cookie must be explicitly specified with + option -setcookie.

-

Under Windows the batch file etop.bat can be used.

+

Under Windows, batch file etop.bat can be used.

-

The following configuration parameters exist for the - etop tool. When executing the etop script, - these parameters can be given as command line options, - e.g. etop -node testnode@myhost -setcookie MyCookie.

+

When executing the etop script, configuration + parameters can be specified as command-line options, + for example, etop -node testnode@myhost -setcookie MyCookie. + The following configuration parameters exist for the + tool:

- node - The measured node. -

-Value: atom() -

-Mandatory - setcookie - Cookie to use for the etop node - must be the same - as the cookie on the measured node. -

-Value: atom() - lines - Number of lines (processes) to display. -

-Value: integer() -

-Default: 10 - interval - The time interval (in seconds) between each update of - the display. -

-Value: integer() -

-Default: 5 - accumulate - If true the execution time and reductions are - accumulated. -

-Value: boolean() -

-Default: false - sort - Identifies what information to sort by. -

-Value: runtime | reductions | memory | msg_q

-Default: runtime (reductions if - tracing=off) - tracing - etop uses the erlang trace facility, and thus no + node +

The measured node.

+

Value: atom()

+

Mandatory

 + setcookie +

Cookie to use for the etop node. Must be same as the + cookie on the measured node.

+

Value: atom()

 + lines +

Number of lines (processes) to display.

+

Value: integer()

+

Default: 10

 + interval +

Time interval (in seconds) between each update of + the display.

+

Value: integer()

+

Default: 5

 + accumulate +

If true, the execution time and reductions are + accumulated.

+

Value: boolean()

+

Default: false

 + sort +

Identifies what information to sort by.

+

Value: runtime | reductions | memory | msg_q

+

Default: runtime (reductions if tracing=off)

 + tracing +

etop uses the Erlang trace facility, and thus no other tracing is possible on the measured node while etop is running, unless this option is set to off. Also helpful if the etop tracing causes too high load on the measured node. With tracing off, runtime is - not measured. -

-Value: on | off

-Default: on + not measured.

+

Value: on | off

+

Default: on

 -

See the user's guide for - more information about the etop tool.

+

For detalis about Erlang Top, see the + User's Guide.

 start() -> ok - Start etop + Start etop. -

This function starts etop. - Note that etop is preferably started with the etop script.

+

Starts etop. + Notice that etop is preferably started with the etop script.

 start(Options) -> ok - Start etop + Start etop. Options = [Option] Option = {Key, Value} @@ -125,31 +115,30 @@ Default: on Value = term() -

This function starts etop. Use - help/0 to see a - description of the possible options.

+

Starts etop. To view the possible options, use + help/0.

 help() -> ok - Print etop's help + Display the etop help. -

This function prints the help of etop and +

Displays the help of etop and its options.

 config(Key,Value) -> Result - Change tool's configuration + Change the configuration of the tool. Result = ok | {error,Reason} Key = lines | interval | accumulate | sort Value = term() -

This function is used to change the tool's configuration - parameters during runtime. The table above indicates the - allowed values for each parameter.

+

Changes the configuration parameters of the tool during runtime. + Allowed parameters are lines, interval, accumulate, + and sort.

 @@ -160,14 +149,14 @@ Default: on File = string() -

This function dumps the current display to a text file.

+

Dumps the current display to a text file.

 stop() -> stop - Terminate etop + Terminate etop. -

This function terminates etop.

+

Terminates etop.

 diff --git a/lib/observer/doc/src/etop_ug.xml b/lib/observer/doc/src/etop_ug.xml index 7059f689d3..d663b089c2 100644 --- a/lib/observer/doc/src/etop_ug.xml +++ b/lib/observer/doc/src/etop_ug.xml @@ -4,7 +4,7 @@
- 20022013 + 20022016 Ericsson AB. All Rights Reserved. @@ -32,15 +32,25 @@
Introduction -

Erlang Top, etop is a tool for presenting information - about erlang processes similar to the information presented by +

Erlang Top, etop, is a tool for presenting information + about Erlang processes similar to the information presented by top in UNIX.

+
+ Getting Started +

Start Erlang Top in either of the following ways:

+ + Use script etop. + Use batch file etop.bat, for example, + etop -node tiger@durin. + +
+
Output -

The output from etop looks like this:

+

The output from Erlang Top is as follows:

The header includes some system information:

- Load - cpu is Runtime/Wallclock, i.e. the - percentage of time where the node has been - active, procs is the number of processes on the node, - and runq is the number of processes that are ready to - run. - Memory - This is the memory allocated by the node in kilo bytes. + Load + + + cpu +

Runtime/Wallclock, that is, the percentage of time + where the node has been active.

 + procs +

The number of processes on the node.

 + runq +

The number of processes that are ready to run.

 + + + Memory +

The memory allocated by the node in kilobytes.

For each process the following information is presented:

- Time - This is the runtime for the process, i.e. the actual - time the process has been scheduled in. - Reds - This is the number of reductions that has been executed - on the process - Memory - This is the size of the process in bytes, obtained by a - call to process_info(Pid,memory). - MsgQ - This is the length of the message queue for the process. + Time +

The runtime for the process, that is, the time that the process + has been scheduled in.

 + Reds +

The number of reductions executed on the process.

 + Memory +

The size of the process in bytes, obtained by a + call to process_info(Pid,memory).

 + MsgQ +

The length of the message queue for the process.

Time and Reds can be presented as - accumulated values or as values since last update.

+ accumulated values or as values since the last update.
-
- Start -

To start etop use the script - etop or the batch file etop.bat, e.g. etop -node tiger@durin, -

-
- -
+
Configuration

All configuration parameters can be set at start by adding - -OptName Value to the command line, e.g. etop -node tiger@durin -setcookie mycookie -lines 15. -

-

The parameters lines, interval, accumulate - and sort can be changed during runtime by the - function etop:config/2. -

-

A list of all valid configuration parameters can be found in - the reference manual for etop. + -OptName Value to the command line, for example:

+ 
+% etop -node tiger@durin -setcookie mycookie -lines 15
+ +

A list of all valid Erlang Top configuration parameters is available in + module etop.

-
- Example: Change configuration with text based presentation - The parameters lines, interval, accumulate, + and sort can be changed during runtime with function + etop:config/2. +

+

Example:

+

Change configuration parameter lines with text-based presentation. + Before the change, 10 lines are presented as follows:

+ ddll_server 0 582 3744 0 gen_server:loop/6 <127.5.0> application_controll 0 569 6756 0 gen_server:loop/6 ======================================================================================== ]]> -

etop:config(lines,5).

-ok

+

Function etop:config/2 is called to change the number of showed + lines to 5:

+ + 
+> etop:config(lines,5).
+ok
+ +

After the change, 5 lines are presented as follows:

======================================================================================== @@ -156,19 +173,20 @@ Pid Name or Initial Func Time Reds Memory MsgQ Current Func <127.43.0> ddll_server 0 0 3744 0 gen_server:loop/6 ======================================================================================== ]]> -
- Print to file -

At any time, the current etop display can be dumped to a - text file with the function etop:dump/1. + Print to File +

At any time, the current Erlang Top display can be dumped to a + text file with function + etop:dump/1.

Stop -

Use the function etop:stop/0 to stop etop. +

To stop Erlang Top, use function + etop:stop/0.

diff --git a/lib/observer/doc/src/introduction_ug.xml b/lib/observer/doc/src/introduction_ug.xml new file mode 100644 index 0000000000..21f0dc709f --- /dev/null +++ b/lib/observer/doc/src/introduction_ug.xml @@ -0,0 +1,49 @@ + + + + +
+ + 20162016 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Introduction + + + + + introduction_ug.xml +
+
+ Scope +

The Observer application is a container including the following + tools for tracing and investigation of distributed systems:

+ + Observer + Trace Tool Builder + Erlang Top + Crashdump Viewer + +
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language.

+
+ diff --git a/lib/observer/doc/src/observer.xml b/lib/observer/doc/src/observer.xml index bba5b1e33c..4d43ffe39f 100644 --- a/lib/observer/doc/src/observer.xml +++ b/lib/observer/doc/src/observer.xml @@ -4,7 +4,7 @@
- 20112013 + 20112016 Ericsson AB, All Rights Reserved @@ -34,24 +34,25 @@ observer.xml
observer - A GUI tool for observing an erlang system. + A GUI tool for observing an Erlang system. -

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 ttb. +

Observer is a graphical tool for observing the characteristics of + Erlang systems. The tool Observer displays system information, application + supervisor trees, process information, ETS tables, Mnesia tables, + and contains a front end for Erlang tracing with module + ttb.

-

See the user's guide - for more information about how to get started.

+

For detalis about how to get started, see the + User's Guide.

 start() -> ok - Start the observer gui + Start the Observer GUI. -

This function starts the observer gui. - Close the window to stop the application. +

Starts the Observer GUI. + To stop the tool, close the window.

diff --git a/lib/observer/doc/src/observer_app.xml b/lib/observer/doc/src/observer_app.xml index 543216cee9..a52d6cb4d9 100644 --- a/lib/observer/doc/src/observer_app.xml +++ b/lib/observer/doc/src/observer_app.xml @@ -4,8 +4,7 @@
- 2002 - 2013 + 20022016 Ericsson AB, All Rights Reserved @@ -24,7 +23,7 @@ The Initial Developer of the Original Code is Ericsson AB. - observer + Observer Siri Hansen Siri Hansen @@ -32,26 +31,21 @@ 2002-04-08 PA1 - observer_app.sgml + observer_app.xml
- observer + Observer The Observer Application -

This chapter describes the OBSERVER application in - OTP, which provides tools for tracing and investigation of - distributed systems.

+

The Observer application contains tools for tracing and + investigation of distributed systems.
Configuration -

There are currently no configuration parameters available for +

No configuration parameters are available for this application.

-
- SEE ALSO -

-
diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml index ff30d70913..ca354df864 100644 --- a/lib/observer/doc/src/observer_ug.xml +++ b/lib/observer/doc/src/observer_ug.xml @@ -4,7 +4,7 @@
- 20112014 + 20112016 Ericsson AB. All Rights Reserved. @@ -32,179 +32,253 @@
Introduction -

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. +

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.

- General -

Normally observer should be run from a standalone node to minimize - the impact of the system being observed. Example: + Getting Started +

Run Observer from a standalone node to minimize the impact of the + system being observed.

- - > erl -sname observer -hidden -setcookie MyCookie -run observer - +

Example:

+ 
+% erl -sname observer -hidden -setcookie MyCookie -run observer

- Choose which node to observe via Nodes menu. The View/Refresh - Interval controls how frequent the view should be updated. + Select the node to observe with menu Nodes. + Menu View > Refresh interval 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.

-

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. +

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.

- Applications -

The Applications view lists application information. + System Tab +

Tab System displays general information about the active Erlang node + and its runtime system, such as build configuration, system capabilities, and + overall use statistics. +

+
+ +
+ Load Charts Tab +

Tab Load Charts displays graphs of the current resource use on + the active Erlang node.

+

Graph Scheduler Utilization shows scheduler use per scheduler, + where each scheduler use has a unique color.

+

Graph Memory Usage shows the total memory use and per memory category + use, where each category has a unique color. The categories are as + follows:

+ + Total +

The sum of all memory categories.

 + Processes +

The sum of all process memory used.

 + Atom +

The size used by the atom table.

 + Binary +

The sum of all off-heap binaries allocated.

 + Code +

The memory allocated for code storage.

 + Ets +

The used memory for all ETS tables.

 + + +

Graph IO Usage shows the current I/O load on the system.

+
+ +
+ Memory Allocators Tab +

Tab Memory Allocators displays detailed information of the carrier + size and current memory carriers. For details about memory carriers, + see module + erts_alloc + in application ERTS.

+
+ +
+ Applications Tab +

Tab Applications presents application information. Select an application in the left list to display its supervisor - tree. -

-

Trace process will add the selected process identifier - to Trace Overview view and the node the process resides on - will be added as well. -

-

Trace named process 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. -

-

Trace process tree and Trace named process - tree will add the selected process and all processes below, - right of, it to the Trace Overview view. + tree. The right-click options in the tree are as follows:

+ + Process info +

Opens a detailed information window on the selected process, + including the following:

+ + Process Information +

Shows the process information.

 + Messages +

Shows the process messages.

 + Dictionary +

Shows the process dictionary.

 + Stack Trace +

Shows the process current stack trace.

 + State +

Shows the process state.

 + Log +

If enabled and available, shows the process SASL + log entries.

 + + + Trace process +

Adds the selected process identifier to tab Trace Overview + plus the node that the process resides on.

 + Trace named process +

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.

 + Trace process tree +

Adds the selected process and all processes below, + right of it, to tab Trace Overview.

 + Trace named process tree +

Adds the selected process and all processes below, + right of it, to tab Trace Overview.

 +
- Processes -

The Processes view lists process information. - For each process the following information is presented: + Processes Tab +

Tab Processes lists process information in columns. + For each process the following information is displayed:

Pid - The process identifier. +

The process identifier.

 Reds - This is the number of reductions that has been executed - on the process +

The number of reductions executed on the process. + This can be presented as accumulated values or as values since the last update.

 Memory - This is the size of the process in bytes, obtained by a - call to process_info(Pid,memory). +

The size of the process, in bytes, obtained by a + call to process_info(Pid,memory).

 MsgQ - This is the length of the message queue for the process. +

The length of the message queue for the process.

 - -

Reds can be presented as accumulated values or as values since last update.

- -

Process info open a detailed information window on the selected process.

+ +

Option Process info opens a detailed information window on the selected process, + including the following:

Process Information - Shows the process information. +

Shows the process information.

 Messages - Shows the process messages. +

Shows the process messages.

 Dictionary - Shows the process dictionary. +

Shows the process dictionary.

 Stack Trace - Shows the process current stack trace. +

Shows the process current stack trace.

 State - Show the process state. +

Shows the process state.

 Log - If enabled and available, show the process SASL log entries. +

If enabled and available, shows the process SASL log entries.

 + -

Log 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. - rb server must not be started on the observed node when clicking on menu 'Log/Toggle log view'. - rb server will be stopped on the observed node when exiting or changing observed node. +

Log requires application SASL to be started on the observed node, + with log_mf_h as log handler. + The Observed node must be Erlang/OTP R16B02 or higher. + The rb server must not be started on the observed node when clicking menu + Log > Toggle log view. The rb server is stopped on the observed node + when exiting or changing the observed node.

-

Trace Processes will add the selected process identifiers to the Trace Overview view and the - node the processes reside on will be added as well. - Trace Named Processes 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. + +

Option Trace Processes adds the selected process identifiers to tab + Trace Overview plus the node that the processes reside on.

+

Option Trace Named Processes 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.

+
- Table Viewer -

The Table Viewer 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 View menu to view "system" - ets tables, unreadable ets tables or mnesia tables. + Table Viewer Tab +

Tab Table Viewer lists tables. By default, ETS tables + are displayed whereas unreadable private ETS tables and tables created by OTP + applications are not diplayed. Use menu View to view "system" + ETS tables, unreadable ETS tables, or Mnesia tables.

-

Double click to view the content of the table. Select table and activate View/Table Information - menu to view table information. -

-

In the table viewer you can regexp search for objects, edit and delete objects. +

Double-click to view the table content. To view table information, select the table + and activate menu View > Table information.

+

You can use regular + expressions and search for objects, and edit or delete them.

- Trace Overview -

The Trace Overview 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 spawn, - exit and several others. -

- -

When you want to trace function calls, you also need to setup - trace patterns. Trace patterns selects the function calls - that will be traced. The number of traced function calls can be - further reduced with match specifications. Match - specifications can also be used to trigger additional information + Trace Overview Tab +

Tab Trace Overview 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 spawn, + exit, and many others. +

+ +

To trace function calls, you also need to set up + trace patterns. Trace patterns select the function calls + to be traced. The number of traced function calls can be + further reduced with match specifications. Match + specifications can also be used to trigger more information in the trace messages.

-

Trace patterns only applies to the traced processes.

 +

Trace patterns only apply to the traced processes.

- Processes are added from the Applications or Processes views. - A special new identifier, meaning all processes spawned after trace start, - can be added with the Add 'new' Process button. + Processes are added from the Applications or Processes tabs. + A special new identifier, meaning all processes spawned after trace + start, can be added with button Add 'new' Process.

- 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, 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.

- Processes added by process identifiers will add the nodes these - processes resides on in the node list. Additional nodes can be added by the Add - Nodes button. + Processes added by process identifiers add the nodes these + processes reside on in the node list. More nodes can be added by clicking + button Add Nodes.

- If function calls are traced, trace patterns must be added by Add Trace Pattern button. - Select a module, function(s) and a match specification. - If no functions are selected, all functions in the module will be traced. + If function calls are traced, trace patterns must be added by clicking button + Add Trace Pattern. Select a module, function(s), and a match specification. + If no functions are selected, all functions in the module are 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 ERTS User's Guide. To simplify - the writing of a match specification they can also be written as - fun/1 see ms_transform manual page for - further information. -

- -

Use the Start trace 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 Stop Trace button. - Trace output can be changed via Options/Output menu. - The trace settings, including match specifications, can be saved to, or loaded from, a file. -

-

More information about tracing can be found in dbg and in the chapter "Match - specifications in Erlang" in ERTS User's - Guide and the - ms_transform manual page. + specifications is described in the ERTS User's Guide. To simplify + the writing of a match specification, they can also be written as + fun/1. For details, see module + ms_transform + in application STDLIB. +

+ +

Click button Start Trace 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 Stop Trace. + Trace output can be changed with menu Options > Output. + The trace settings, including match specifications, can be saved to, + or loaded from, a file. +

+

For details about tracing, see module dbg in application Runtime_Tools + and in section "Match specifications in Erlang" in + ERTS User's Guide + and in module + ms_transform + in application STDLIB.

diff --git a/lib/observer/doc/src/part.xml b/lib/observer/doc/src/part.xml index 27b4e93d2d..d8ec7664d9 100644 --- a/lib/observer/doc/src/part.xml +++ b/lib/observer/doc/src/part.xml @@ -29,9 +29,8 @@
-

The Observer application contains tools for tracing - and investigation of distributed systems.

 + diff --git a/lib/observer/doc/src/ref_man.xml b/lib/observer/doc/src/ref_man.xml index 03d7dbe9df..37e20b2643 100644 --- a/lib/observer/doc/src/ref_man.xml +++ b/lib/observer/doc/src/ref_man.xml @@ -30,10 +30,7 @@ application.sgml
-

The Observer application contains tools for tracing - and investigation of distributed systems.

-

- + diff --git a/lib/observer/doc/src/ttb.xml b/lib/observer/doc/src/ttb.xml index 0a50a20716..2b637551db 100644 --- a/lib/observer/doc/src/ttb.xml +++ b/lib/observer/doc/src/ttb.xml @@ -4,8 +4,7 @@
- 2002 - 2013 + 20022016 Ericsson AB, All Rights Reserved @@ -25,27 +24,28 @@ ttb - Siri hansen, Bartlomiej Puzon + Siri Hansen, Bartlomiej Puzon 1 2010-08-13 PA1 - ttb.sgml + ttb.xml
ttb A base for building trace tools for distributed systems. -

The Trace Tool Builder ttb is a base for building trace +

The Trace Tool Builder, ttb, is a base for building trace tools for distributed systems.

-

When using ttb, dbg shall not be used in parallel.

+

When using ttb, do not use module dbg in application + Runtime_Tools in parallel.

 start_trace(Nodes, Patterns, FlagSpec, Opts) -> Result - Start a trace port on each given node. + Start a trace port on each specified node. Result = see p/2 Nodes = see tracer/2 @@ -57,48 +57,56 @@

This function is a shortcut allowing to start a trace with one command. Each - tuple in Patterns is converted to list which is in turn passed to - ttb:tpl. - The call:

-ttb:start_trace([Node, OtherNode], -[{mod, foo, []}, {mod, bar, 2}], -{all, call}, -[{file, File}, {handler,{fun myhandler/4, S}}]) -

is equivalent to

-ttb:start_trace([Node, OtherNode], [{file, File}, {handler,{fun myhandler/4, S}}]), + tuple in Patterns is converted to a list, which in turn is passed to + ttb:tpl/2,3,4.

+

The call:

+ 
+> ttb:start_trace([Node, OtherNode],
+                  [{mod, foo, []}, {mod, bar, 2}],
+                  {all, call},
+                  [{file, File}, {handler,{fun myhandler/4, S}}]).
+

is equivalent to:

+ 
+> ttb:start_trace([Node, OtherNode],
+                  [{file, File}, {handler,{fun myhandler/4, S}}]),
 ttb:tpl(mod, foo, []),
 ttb:tpl(mod, bar, 2, []),
-ttb:p(all, call)
+ttb:p(all, call).
 + tracer() -> Result - This is equivalent to tracer(node()). + Equivalent to tracer(node()). -

This is equivalent to tracer(node()).

+

Equivalent to tracer(node()).

 + tracer(Shortcut) -> Result - Handy shortcuts for common tracing settings + Handy shortcuts for common tracing settings. Shortcut = shell | dbg +

Handy shortcuts for common tracing settings.

shell is equivalent to tracer(node(),[{file, {local, "ttb"}}, shell]).

dbg is equivalent to tracer(node(),[{shell, only}]).

 + tracer(Nodes) -> Result - This is equivalent to tracer(Nodes,[]). + Equivalent to tracer(Nodes,[]). -

This is equivalent to tracer(Nodes,[]).

+

Equivalent to tracer(Nodes,[]).

 + tracer(Nodes,Opts) -> Result - Start a trace port on each given node. + Start a trace port on each specified node. Result = {ok, ActivatedNodes} | {error,Reason} Nodes = atom() | [atom()] | all | existing | new @@ -120,98 +128,109 @@ ttb:p(all, call) ShellSpec = true | false | only -

This function starts a file trace port on all given nodes - and also points the system tracer for sequential tracing to +

Starts a file trace port on all specified nodes + and points the system tracer for sequential tracing to the same port.

-

The given Filename will be prefixed with the node - name. Default Filename is "ttb". -

-

File={wrap,Filename,Size,Count} can be used if - the size of the trace logs must be limited. Default values are - Size=128*1024 and Count=8. -

-

When tracing diskless nodes, ttb must be started +

Options:

+ + Filename +

The specified Filename is prefixed with the node name. + Default Filename is ttb.

 + File={wrap,Filename,Size,Count} +

Can be used if the size of the trace logs must be limited. + Default values are + Size=128*1024 and Count=8.

 + Client +

When tracing diskless nodes, ttb must be started from an external "trace control node" with disk access, and Client must be {local, File}. All trace information is then sent to the trace control node where - it is written to file. -

-

The process_info option indicates if process - information should be collected. If PI = true (which is + it is written to file.

 + process_info +

Indicates if process + information is to be collected. If PI = true (which is default), each process identifier Pid is replaced by a tuple {Pid,ProcessInfo,Node}, where ProcessInfo - is the process' registered name its globally registered name, - or its initial function. It is possible to turn off this - functionality by setting PI = false. -

-

The {shell, ShellSpec} option indicates that the trace messages should - be printed on the console as they are received by the tracing - process. This implies {local, File} trace client. If the ShellSpec - is only (instead of true), no trace logs are stored. -

-

The shell option is a shortcut for {shell, true}.

-

The timer option indicates that the trace should be + is the registered process name, its globally registered name, + or its initial function. To turn off this functionality, + set PI = false.

 + {shell, ShellSpec} +

Indicates that trace messages are to be printed on the + console as they are received by the tracing process. This implies + trace client {local, File}. If ShellSpec + is only (instead of true), no trace logs are stored.

 + shell +

Shortcut for {shell, true}.

 + timer +

Indicates that the trace is to be automatically stopped after MSec milliseconds. StopOpts - are passed to ttb:stop/2 command if specified (default is []). - Note that the timing is approximate, as delays related to + are passed to command ttb:stop/2 if specified (default is []). + Notice that the timing is approximate, as delays related to network communication are always present. The timer starts after - ttb:p/2 is issued, so you can set up your trace patterns before. -

-

The overload_check option allows to enable overload + ttb:p/2 is issued, so you can set up your trace patterns before.

 + overload_check +

Allows to enable overload checking on the nodes under trace. Module:Function(check) - is performed each MSec milliseconds. If the check returns - true, the tracing is disabled on a given node.
- Module:Function should be able to handle at least three - atoms: init, check and stop. init and - stop give the user a possibility to initialize and clean - up the check environment.
- When a node gets overloaded, it is not possible to issue ttb:p - nor any command from the ttb:tp family, as it would lead to + is performed each MSec millisecond. If the check returns + true, the tracing is disabled on a specified node.

+

Module:Function must be able to handle at least three + atoms: init, check, and stop. init and + stop allows you to initialize and clean + up the check environment.

+

When a node gets overloaded, it is not possible to issue ttb:p/2 + or any command from the ttb:tp/2,3,4 family, as it would lead to inconsistent tracing state (different trace specifications on - different node). -

-

The flush option periodically flushes all file trace - port clients (see dbg:flush_trace_port/1). When enabled, - the buffers are freed each MSec milliseconds. This option is - not allowed with {file, {local, File}} tracing. -

-

{resume, FetchTimeout} enables the autoresume feature. - Whenever enabled, remote nodes try to reconnect to the controlling node - in case they were restarted. The feature requires runtime_tools - application to be started (so it has to be present in the .boot - scripts if the traced nodes run with embedded erlang). If this is - not possible, resume may be performed manually by starting - runtime_tools remotely using rpc:call/4.
- ttb tries to fetch all logs from a reconnecting node before - reinitializing the trace. This has to finish within FetchTimeout milliseconds - or is aborted
- By default, autostart information is stored in a file called + different nodes).

 + flush +

Periodically flushes all file trace + port clients (see + + dbg:flush_trace_port/1). When enabled, + the buffers are freed each MSec millisecond. This option is + not allowed with {file, {local, File}} tracing.

 + {resume, FetchTimeout} +

Enables the autoresume feature. + When enabled, remote nodes try to reconnect to the controlling node + if they are restarted. The feature requires application Runtime_Tools + to be started (so it has to be present in the .boot + scripts if the traced nodes run with embedded Erlang). If this is + not possible, resume can be performed manually by starting + Runtime_Tools remotely using + rpc:call/4.

+

ttb tries to fetch all logs from a reconnecting node before + reinitializing the trace. This must finish within FetchTimeout + milliseconds or is aborted.

+

By default, autostart information is stored in a file named ttb_autostart.bin on each node. If this is not desired - (i.e. on diskless nodes), a custom module to handle autostart + (for example, on diskless nodes), a custom module handling autostart information storage and retrieval can be provided by specifying - ttb_autostart_module environment variable for the runtime_tools - application. The module has to respond to the following API:

- + environment variable ttb_autostart_module for the application + Runtime_Tools. The module must respond to the following API:

+ write_config(Data) -> ok - Store the provided data for further retrieval. It is +

Stores the provided data for further retrieval. It is important to realize that the data storage used must not - be affected by the node crash. + be affected by the node crash.

 read_config() -> {ok, Data} | {error, Error} - Retrieve configuration stored with write_config(Data). +

Retrieves configuration stored with write_config(Data).

 delete_config() -> ok - Delete configuration stored with write_config(Data). - Note that after this call any subsequent calls to read_config - must return {error, Error}. +

Deletes configuration stored with write_config(Data). + Notice that after this call any subsequent calls to read_config + must return {error, Error}.

 - -

The resume option implies the default FetchTimeout, which is + +

resume implies the default FetchTimeout, which is 10 seconds

+ + + + p(Procs,Flags) -> Return - Sets the given trace flags on the given processes. + Set the specified trace flags on the specified processes. Return = {ok,[{Procs,MatchDesc}]} Procs = Process | [Process] | all | new | existing @@ -219,95 +238,101 @@ ttb:p(all, call) Flags = Flag | [Flag] -

This function sets the given trace flags on the given - processes. The timestamp flag is always turned on. +

Sets the specified trace flags on the specified + processes. Flag timestamp is always turned on.

-

Please turn to the Reference manual for module dbg - for details about the possible trace flags. The parameter - MatchDesc is the same as returned from dbg:p/2

-

Processes can be given as registered names, globally - registered names or process identifiers. If a registered name - is given, the flags are set on processes with this name on all +

See the Reference Manual for module + dbg + and the possible trace flags. Parameter + MatchDesc is the same as returned from + dbg:p/2.

+

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.

-

Issuing this command starts the timer for this trace if - timer option was specified with tracer/2. +

Issuing this command starts the timer for this trace if option + timer is specified with tracer/2.

+ tp, tpl, ctp, ctpl, ctpg Set and clear trace patterns. -

These functions should be used in combination with the - call trace flag for setting and clearing trace - patterns. When the call trace flag is set on a process, - function calls will be traced on that process if a trace - pattern has been set for the called function. Trace patterns - specifies how to trace a function by using match +

These functions are to be used with + trace flag call for setting and clearing trace + patterns. When trace flag call 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 - User's Guide for the erlang runtime system erts. + ERTS User's Guide.

These functions are equivalent to the corresponding - functions in dbg, but all calls are stored in the - history. The history buffer makes it easy to create config - files so that the same trace environment can be setup several - times, e.g. if you want to compare two test runs. It also + functions in module + dbg, + but all calls are stored in the + history. The history buffer makes it easy to create configuration + files; the same trace environment can be set up many + times, for example, to compare two test runs. It also reduces the amount of typing when using ttb from the - erlang shell. + Erlang shell.

tp - Set trace pattern on global function calls +

Sets trace patterns on global function calls.

 tpl - Set trace pattern on local and global function calls +

Sets trace patterns on local and global function calls.

 ctp - Clear trace pattern on local and global function - calls +

Clears trace patterns on local and global function + calls.

 ctpl - Clear trace pattern on local function calls +

Clears trace patterns on local function calls.

 ctpg - Clear trace pattern on global function calls +

Clears trace patterns on global function calls.

 -

With tp and tpl one of match specification shortcuts - may be used (example: ttb:tp(foo_module, caller)). The shortcuts are:

- - +

With tp and tpl, one of the match specification shortcuts + can be used (for example, ttb:tp(foo_module, caller)).

+

The shortcuts are as follows:

+ return - for [{'_',[],[{return_trace}]}] (report the return value) - caller - for [{'_',[],[{message,{caller}}]}] (report the calling function) - {codestr, Str} - for dbg:fun2ms/1 arguments passed as strings (example: "fun(_) -> return_trace() end") - + + list_history() -> History - Returns all calls stored in history + Return all calls stored in history. History = [{N,Func,Args}]

All calls to ttb is stored in the history. This function returns the current content of the history. Any entry - can be re-executed with run_history/1 or stored in a - config file with write_config/2/3.

+ can be reexecuted with run_history/1 or stored in a + configuration file with write_config/2,3.

 + run_history(N) -> ok | {error, Reason} - Executes one entry of the history + Execute one entry of the history. N = integer() | [integer()] -

Executes the given entry or entries from the history - list. History can be listed with list_history/0.

+

Executes the specified entry or entries from the history + list. To list history, use list_history/0.

 + write_config(ConfigFile,Config) Equivalent to write_config(ConfigFile,Config,[]). @@ -315,9 +340,10 @@ ttb:p(all, call)

Equivalent to write_config(ConfigFile,Config,[]).

 + write_config(ConfigFile,Config,Opts) -> ok | {error,Reason} - Creates a config file. + Create a configuration file. ConfigFile = string() Config = all | [integer()] | [{Mod,Func,Args}] @@ -328,92 +354,97 @@ ttb:p(all, call) Opt = append -

This function creates or extends a config file which can be +

Creates or extends a configuration file, which can be used for restoring a specific configuration later.

-

The content of the config file can either be fetched from - the history or given directly as a list of +

The contents of the configuration file can either be fetched from + the history or specified directly as a list of {Mod,Func,Args}.

-

If the complete history is to be stored in the config file - Config should be all. If only a selected number - of entries from the history should be stored, Config - should be a list of integers pointing out the entries to be +

If the complete history is to be stored in the configuration file, + Config must be all. If only a selected number + of entries from the history are to be stored, Config + must be a list of integers pointing out the entries to be stored.

-

If Opts is not given or if it is [], +

If Opts is not specified or if it is [], ConfigFile is deleted and a new file is created. If - Opts = [append], ConfigFile will not be deleted. - The new information will be appended at the end of the file.

+ Opts = [append], ConfigFile is not deleted. + The new information is appended at the end of the file.

 + run_config(ConfigFile) -> ok | {error,Reason} - Executes all entries in a config file. + Execute all entries in a configuration file. ConfigFile = string() -

Executes all entries in the given config file. Note that the history - of the last trace is always available in the file named - ttb_last_config.

+

Executes all entries in the specified configuration file. + Notice that the history of the last trace is always available + in file ttb_last_config.

 + run_config(ConfigFile,NumList) -> ok | {error,Reason} - Executes selected entries from a config file. + Execute selected entries from a configuration file. ConfigFile = string() NumList = [integer()] -

Executes selected entries from the given config +

Executes selected entries from the specified configuration file. NumList is a list of integers pointing out the entries to be executed.

-

The content of a config file can be listed with +

To list the contents of a configuration file, use list_config/1.

-

Note that the history - of the last trace is always available in the file named - ttb_last_config.

+

Notice that the history of the last trace is always available + in file ttb_last_config.

 + list_config(ConfigFile) -> Config | {error,Reason} - Lists all entries in a config file. + List all entries in a configuration file. ConfigFile = string() Config = [{N,Func,Args}] -

Lists all entries in the given config file.

+

Lists all entries in the specified configuration file.

 + write_trace_info(Key,Info) -> ok - Writes any information to the .tifile. + Write any information to file .ti. Key = term() Info = Data | fun() -> Data Data = term() -

The .ti file contains {Key,ValueList} - tuples. This function adds Data to the ValueList +

File .ti contains {Key,ValueList} + tuples. This function adds Data to the ValueList associated with Key. All information written with this - function will be included in the call to the format handler.

+ function is included in the call to the format handler.

 + seq_trigger_ms() -> MatchSpec - Equivalent to seq_trigger_ms(all) + Equivalent to seq_trigger_ms(all). -

Equivalent to seq_trigger_ms(all)

+

Equivalent to seq_trigger_ms(all).

 + seq_trigger_ms(Flags) -> MatchSpec - Returns a match_spec() which starts sequential tracing + Return a match_spec() which starts sequential tracing. MatchSpec = match_spec() Flags = all | SeqTraceFlag | [SeqTraceFlag] @@ -421,54 +452,55 @@ ttb:p(all, call)

A match specification can turn on or off sequential - tracing. This function returns a match specification which - turns on sequential tracing with the given Flags. + tracing. This function returns a match specification, which + turns on sequential tracing with the specified Flags.

-

This match specification can be given as the last argument - to tp or tpl. The activated Item will - then become a trigger for sequential tracing. This - means that if the item is called on a process with the - call trace flag set, the process will be "contaminated" - with the seq_trace token. +

This match specification can be specified as the last argument + to tp or tpl. The activated Item + then becomes a trigger for sequential tracing. This + means that if the item is called on a process with trace flag + call set, the process is "contaminated" + with token seq_trace.

If Flags = all, all possible flags are set.

-

Please turn to the reference manual for the - seq_trace module in the kernel - application to see the possible values for - SeqTraceFlag. For a description of the match_spec() - syntax, please turn to the User's guide for the - runtime system (erts). The chapter Match Specification in Erlang explains the general match - specification "language". +

The possible values for SeqTraceFlag are available in + seq_trace.

+

For a description of the match_spec() syntax, + see section + Match Specifications in Erlang + in ERTS, which explains the general match specification "language".

The system tracer for sequential tracing is automatically initiated by ttb when a trace port is - started with ttb:tracer/0/1/2.

+ started with ttb:tracer/0,1,2.

 -

Example of how to use the seq_trigger_ms/0/1 function:

- -(tiger@durin)5> ttb:tracer(). +

An example of how to use function seq_trigger_ms/0,1 follows:

+ 
+(tiger@durin)5> ttb:tracer().
 {ok,[tiger@durin]}
-(tiger@durin)6> ttb:p(all,call).
+(tiger@durin)6> ttb:p(all,call).
 {ok,{[all],[call]}}
-(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
+(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
 {ok,[{matched,1},{saved,1}]}
-(tiger@durin)8>         
-        
Whenever mod:func(...) is called after this, the
-          seq_trace token will be set on the executing process.

+(tiger@durin)8>
+

Whenever mod:func(...) is called after this, + token seq_trace is set on the executing process.

 + stop() - Equivalent to stop([]) + Equivalent to stop([]).

Equivalent to stop([]).

 + stop(Opts) -> stopped | {stopped, Dir} - Stop tracing and fetch/format logs from all nodes + Stop tracing and fetch/format logs from all nodes. Opts = Opt | [Opt] Opt = nofetch | {fetch_dir, Dir} | format | {format, FormatOpts} | return_fetch_dir @@ -485,88 +517,103 @@ ttb:p(all, call) form yyyymmdd-hhmmss. Even logs from nodes on the same machine as the trace control node are moved to this directory. The history list is saved to a file named ttb_last_config - for further reference (as it will be not longer accessible - through history and configuration management functions (like + for further reference (as it is no longer accessible + through history and configuration management functions, like ttb:list_history/0).

-

The nofetch option indicates that trace logs shall not be - collected after tracing is stopped. -

-

The {fetch, Dir} option allows to specify the directory +

Options:

+ + nofetch +

Indicates that trace logs are not to be + collected after tracing is stopped.

 + {fetch, Dir} +

Allows specification of the directory to fetch the data to. If the directory already exists, an - error is thrown. -

-

The format option indicates that the trace logs - shall be formatted after tracing is stopped. All logs in the fetch directory will be merged. - You may use {format, FormatOpts} to pass additional - arguments to format/2.

-

The return_fetch_dir option indicates that the return value - should be {stopped, Dir} and not just stopped. - This implies fetch. -

+ error is thrown.

 + format +

Indicates the trace logs to be formatted after tracing + is stopped. All logs in the fetch directory are merged.

 + return_fetch_dir +

Indicates the return value + to be {stopped, Dir} and not just stopped. + This implies fetch.

 + + + get_et_handler() - Returns et handler. + Return the et handler. -

The et handler returned by the function may be used with format/2 - or tracer/2. Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).

+

Returns the et handler, which can be used with format/2 + or tracer/2.

+

Example: ttb:format(Dir, [{handler, ttb:get_et_handler()}]).

 + format(File) - Same as format(File,[]). + Equivalent to format(File,[]). -

Same as format(File,[]).

+

Equivalent to format(File,[]).

 + format(File,Options) -> ok | {error, Reason} - Format a binary trace log + Format a binary trace log. File = string() | [string()] - This can be the name of a binary log, a list of such logs or the name of a directory containing one or more binary logs. + This can be the name of a binary log, a list of such logs, + or the name of a directory containing one or more binary logs. Options = Opt | [Opt] Opt = {out,Out} | {handler,FormatHandler} | disable_sort Out = standard_io | string() FormatHandler = {Function, InitialState} Function = fun(Fd,Trace,TraceInfo,State) -> State Fd = standard_io | FileDescriptor - This is the file descriptor of the destination file Out + File descriptor of the destination file Out. Trace = tuple() - This is the trace message. Please turn to the Reference manual for the erlangmodule for details. + The trace message. For details, see the Reference Manual for + module erlang. TraceInfo = [{Key,ValueList}] - This includes the keys flags, client and node, and if handler is given as option to the tracer function, this is also included. In addition all information written with the write_trace_info/2function is included. + Includes the keys flags, client, and node. + If handler is specified as option to the tracer function, this + is also included. Also, all information written with function + write_trace_info/2 is included. -

Reads the given binary trace log(s). The logs are processed - in the order of their timestamp as long as disable_sort - option is not given. +

Reads the specified binary trace log(s). The logs are processed + in the order of their time stamps as long as option disable_sort + is not specified.

If FormatHandler = {Function,InitialState}, - Function will be called for each trace message. If - FormatHandler = get_et_handler(), et_viewer in - the Event Tracer application (et) is used for presenting + Function is called for each trace message.

+

If FormatHandler = get_et_handler(), et_viewer in + application ET is used for presenting the trace log graphically. ttb provides a few different - filters which can be selected from the Filter menu in the - et_viewer. If FormatHandler is not given, a - default handler is used which presents each trace message as a - line of text. + filters that can be selected from menu Filters and scaling + in the et_viewer.

+

If FormatHandler is not specified, a + default handler is used presenting each trace message as a + text line.

-

The state returned from each call of Function is passed to the next call, - even if next call is to format a message from another log file. +

The state returned from each call of Function is passed to + the next call, even if the next call is to format a message from another + log file.

-

If Out is given, FormatHandler gets the +

If Out is specified, FormatHandler gets the file descriptor to Out as the first parameter.

-

Out is ignored if et format handler is used. +

Out is ignored if the et format handler is used.

-

Wrap logs can be formatted one by one or all in one go. To - format one of the wrap logs in a set, give the exact name of - the file. To format the whole set of wrap logs, give the name - with '*' instead of the wrap count. See examples in the - ttb User's Guide.

+

Wrap logs can be formatted one by one or all at once. To + format one of the wrap logs in a set, specify the exact file name. + To format the whole set of wrap logs, specify the name + with * instead of the wrap count. For examples, see the + User's Guide. +

diff --git a/lib/observer/doc/src/ttb_ug.xml b/lib/observer/doc/src/ttb_ug.xml index e2a28d67d0..34591ae8de 100644 --- a/lib/observer/doc/src/ttb_ug.xml +++ b/lib/observer/doc/src/ttb_ug.xml @@ -4,7 +4,7 @@
- 20022013 + 20022016 Ericsson AB. All Rights Reserved. @@ -32,78 +32,85 @@
Introduction -

The Trace Tool Builder is a base for building trace tools for - single node or distributed erlang systems. It requires the - runtime_tools application to be available on the traced +

Trace Tool Builder is a base for building trace tools for + single node or distributed Erlang systems. It requires the + Runtime_Tools application to be available on the traced node.

-

The main features of the Trace Tool Builder are:

+

The following are the main features of Trace Tool Builder:

- Start tracing to file ports on several nodes with one + Start tracing to file ports on many nodes with one function call. - Write additional information to a trace information file, + Write more information to a trace information file, which is read during formatting. - Restoring of previous configuration by maintaining a + Restore previous configuration by maintaining a history buffer and handling configuration files. - Some simple support for sequential tracing. - Formatting of binary trace logs and merging of logs from + Provide some simple support for sequential tracing. + Format binary trace logs and merge logs from multiple nodes. -

The intention of the Trace Tool Builder is to serve - as a base for tailor made trace tools, but you may use it directly - from the erlang shell (it may mimic dbg behaviour while - still providing useful additions like match specification shortcuts). - The application only - allows the use of file port tracer, so if you would like - to use other types of trace clients you will be better off - using dbg directly instead.

+

The intention of Trace Tool Builder is to serve + as a base for tailor-made trace tools, but it can also be used directly + from the Erlang shell (it can mimic dbg behaviour while + still providing useful additions, such as match specification shortcuts). + Trace Tool Builder only allows the use of file port tracer, so to use + other types of trace clients it is better to use dbg directly.

Getting Started -

The ttb module is the interface to all functions in the - Trace Tool Builder. To get started the least you need to do is to - start a tracer with ttb:tracer/0/1/2, and set the required - trace flags on the processes you want to trace with - ttb:p/2. Then, when the tracing is completed, you must stop - the tracer with ttb:stop/0/1 and format the trace log with - ttb:format/1/2 (as long as there is anything to format, of - course). +

Module ttb is the interface to all functions in + Trace Tool Builder.

+

To get started, the least you need to do is to + start a tracer with + ttb:tracer/0,1,2, + and set the required + trace flags on the processes you want to trace with + ttb:p/2.

+

When the tracing is completed, stop the tracer with + ttb:stop/0,1 + and format the trace log with + ttb:format/1,2 + (if there is anything to format).

-

ttb:tracer/0/1/2 opens a trace port on each node - that shall be traced. By default, trace messages are written - to binary files on remote nodes(the binary trace log). -

-

ttb:p/2 specifies which processes shall be - traced. Trace flags given in this call specify what to trace on - each process. You can call this function several times if you like - different trace flags to be set on different processes. -

-

If you want to trace function calls (i.e. if you have the - call trace flag set on any of your processes), you must +

Useful functions:

+ + ttb:tracer/0,1,2 +

Opens a trace port on each node to be traced. By default, + trace messages are written to binary files on remote nodes (the + binary trace log).

 + ttb:p/2 +

Specifies the processes to be traced. Trace flags specified + in this call specify what to trace on each process. This function can be + called many times if you like different trace flags to be set on different + processes.

 + ttb:tp/2,3,4 or ttb:tpl/2,3,4 +

If you want to trace function calls (that is, if you have + trace flag call set on any process), you must also set trace patterns on the required function(s) with - ttb:tp or ttb:tpl. A function is only traced if it - has a trace pattern. The trace pattern specifies how to trace the + ttb:tp/2,3,4 or + ttb:tpl/2,3,4. + A function is only traced + if it has a trace pattern. The trace pattern specifies how to trace the function by using match specifications. Match specifications are - described in the User's Guide for the erlang runtime system - erts. -

-

ttb:stop/0/1 stops tracing on all nodes, deletes all - trace patterns and flushes the trace port buffer. -

-

ttb:format/1/2 translates the binary trace logs into - something readable. By default ttb presents each trace - message as a line of text, but you can also write your own handler - to make more complex interpretations of the trace information. A - trace log can even be presented graphically via the Event Tracer - application. Note that if you give the format option to - ttb:stop/1 the formatting is automatically done when - stopping ttb. -

- + described in the + ERTS User's Guide.

 + ttb:stop/0,1 +

Stops tracing on all nodes, deletes all trace patterns, and + flushes the trace port buffer.

 + ttb:format/1/2 +

Translates the binary trace logs into something readable. + By default, ttb presents each trace message as a line of text, + but you can also write your own handler to make more complex interpretations + of the trace information. A trace log can also be presented graphically + with application Event Tracer (ET).

+

If option format is specified to ttb:stop/1, the formatting + is automatically done when stopping ttb.

 + +
- Example: Tracing the local node from the erlang shell -

This small module is used in the example:

+ Tracing Local Node from Erlang Shell +

The following small module is used in the subsequent example:

-module(m). -export([f/0]). @@ -114,25 +121,25 @@ f() -> From ! {self(),Now} end.

The following example shows the basic use of ttb from - the erlang shell. Default options are used both for starting the - tracer and for formatting (the custom fetch dir is however provided). - This gives a trace log named Node-ttb in the newly-created - directory, where Node is the name of the node. The + the Erlang shell. Default options are used both for starting the + tracer and for formatting (the custom fetch directory is however provided). + This gives a trace log named Node-ttb in the newly created + directory, where Node is the node name. The default handler prints the formatted trace messages in the - shell.

- + 
 (tiger@durin)47> %% First I spawn a process running my test function
-(tiger@durin)47> Pid = spawn(m,f,[]).
-<0.125.0>
+(tiger@durin)47> Pid = spawn(m,f,[]).
+<0.125.0>
 (tiger@durin)48> 
 (tiger@durin)48> %% Then I start a tracer...
-(tiger@durin)48> ttb:tracer().
+(tiger@durin)48> ttb:tracer().
 {ok,[tiger@durin]}
 (tiger@durin)49> 
 (tiger@durin)49> %% and activate the new process for tracing
 (tiger@durin)49> %% function calls and sent messages.
-(tiger@durin)49> ttb:p(Pid,[call,send]).
-{ok,[{<0.125.0>,[{matched,tiger@durin,1}]}]}
+(tiger@durin)49> ttb:p(Pid,[call,send]).
+{ok,[{<0.125.0>,[{matched,tiger@durin,1}]}]}
 (tiger@durin)50> 
 (tiger@durin)50> %% Here I set a trace pattern on erlang:now/0
 (tiger@durin)50> %% The trace pattern is a simple match spec
@@ -140,33 +147,33 @@ f() ->
 (tiger@durin)50> %% traced. Refer to the reference_manual for
 (tiger@durin)50> %% the full list of match spec shortcuts
 (tiger@durin)50> %% available.
-(tiger@durin)51> ttb:tp(erlang,now,return).
+(tiger@durin)51> ttb:tp(erlang,now,return).
 {ok,[{matched,tiger@durin,1},{saved,1}]}
 (tiger@durin)52> 
 (tiger@durin)52> %% I run my test (i.e. send a message to
 (tiger@durin)52> %% my new process)
-(tiger@durin)52> Pid ! self().
-<0.72.0>
+(tiger@durin)52> Pid ! self().
+<0.72.0>
 (tiger@durin)53> 
 (tiger@durin)53> %% And then I have to stop ttb in order to flush
 (tiger@durin)53> %% the trace port buffer
-(tiger@durin)53> ttb:stop([return, {fetch_dir, "fetch"}]).
+(tiger@durin)53> ttb:stop([return, {fetch_dir, "fetch"}]).
 {stopped, "fetch"}
 (tiger@durin)54> 
 (tiger@durin)54> %% Finally I format my trace log
-(tiger@durin)54> ttb:format("fetch").
-({<0.125.0>,{m,f,0},tiger@durin}) call erlang:now()
-({<0.125.0>,{m,f,0},tiger@durin}) returned from erlang:now/0 ->
+(tiger@durin)54> ttb:format("fetch").
+({<0.125.0>,{m,f,0},tiger@durin}) call erlang:now()
+({<0.125.0>,{m,f,0},tiger@durin}) returned from erlang:now/0 ->
 {1031,133451,667611}
-({<0.125.0>,{m,f,0},tiger@durin}) <0.72.0> ! 
-{<0.125.0>,{1031,133451,667611}}
-ok      ]]>
+({<0.125.0>,{m,f,0},tiger@durin}) <0.72.0> !
+{<0.125.0>,{1031,133451,667611}}
+ok
- Example: Build your own tool -

This small example shows a simple tool for "debug tracing", - i.e. tracing of function calls with return values.

+ Build Your Own Tool +

The following example shows a simple tool for "debug tracing", + that is, tracing of function calls with return values:

"Return value :~p~n~n", [N,Ts,P,M,F,A,R]). ]]>

To distinguish trace logs produced with this tool from other - logs, the file option is used in tracer/2. The - logs will therefore be fetched to a directory named + logs, option file is used in + tracer/2. The + logs are therefore fetched to a directory named ttb_upload_debug_log-YYYYMMDD-HHMMSS

-

By using the handler option when starting the tracer, +

By using option handler when starting the tracer, the information about how to format the file is stored in the trace information file (.ti). This is not necessary, as - it might be given at the time of formatting instead. It can - however be useful if you e.g. want to automatically format your - trace logs by using the format option in - ttb:stop/1. It also means that you don't need any - knowledge of the content of a binary log to be able to format it - the way it was intended. If the handler option is given - both when starting the tracer and when formatting, the one given - when formatting is used. + it can be specified when formatting instead. However, It can + be useful if you, for example, want to format trace logs automatically + using option format in ttb:stop/1. Also, you do not need + any knowledge of the content of a binary log to format it the way it + is intended. If option handler is specified both when starting + the tracer and when formatting, the one specified when formatting is used.

-

The call trace flag is set on all processes. This - means that any function activated with the trc/1 command - will be traced on all existing and new processes. +

Trace flag call is set on all processes. This + means that any function activated with command trc/1 + is traced on all existing and new processes.

- Running the Trace Tool Builder against a remote node + Running Trace Tool Builder against Remote Node

The Observer application might not always be available on the - node that shall be traced (in the following called the "traced - node"). It is still possible to run the Trace Tool Builder from + node to be traced (in the following called the "traced + node"). However, Trace Tool Builder can still be run from another node (in the following called the "trace control node") as - long as + long as the following is fulfilled:

The Observer application is available on the trace control node. - The Runtime Tools application is available on both the + The Runtime_Tools application is available on both the trace control node and the traced node. -

If the Trace Tool Builder shall be used against a remote node, +

If Trace Tool Builder is to be used against a remote node, it is highly recommended to start the trace control node as hidden. This way it can connect to the traced node - without the traced node "seeing" it, i.e. if the nodes() - BIF is called on the traced node, the trace control node will not - show. To start a hidden node, add the -hidden option to the - erl command, e.g.

- -% erl -sname trace_control -hidden + without being "seen" by it, that is, if the nodes() + BIF is called on the traced node, the trace control node does not + show. To start a hidden node, add option -hidden to the + erl command, for example:

+ 
+% erl -sname trace_control -hidden
- Diskless node + Diskless Node

If the traced node is diskless, ttb must be started from - a trace control node with disk access, and the file option - must be given to the tracer/2 function with the value - {local, File}, e.g.

- -(trace_control@durin)1> ttb:tracer(mynode@diskless,{file,{local, -{wrap,"mytrace"}}}). -{ok,[mynode@diskless]} + a trace control node with disk access, and option file + must be specified to function tracer/2 with value + {local, File}, for example:

+ 
+(trace_control@durin)1> ttb:tracer(mynode@diskless,
+                                   {file,{local,{wrap,"mytrace"}}}).
+{ok,[mynode@diskless]}
- Additional tracing options -

When setting up a trace, several features may be turned on:

+ More Tracing Options +

When setting up a trace, the following features can also be activated:

- time-constrained tracing, - overload protection, - autoresuming. + Time-constrained tracing + Overload protection + Autoresume + dbg mode
- Time-constrained tracing -

Sometimes, it may be helpful to enable trace for a - given period of time (i.e. to monitor a system for 24 hours - or half of a second). This may be done by issuing additional - {timer, TimerSpec} option. If TimerSpec has the + Time-Constrained Tracing +

It can sometimes be helpful to enable trace for a + specified period of time (for example, to monitor a system for 24 hours + or half a second). This can be done with option + {timer, TimerSpec}. If TimerSpec has the form of MSec, the trace is stopped after MSec - milliseconds using ttb:stop/0. If any additional options - are provided (TimerSpec = {MSec, Opts}), ttb:stop/1 - is called instead with Opts as the arguments. The timer - is started with ttb:p/2, so any trace patterns should - be set up before. ttb:start_trace/4 - always sets up all pattern before invoking ttb:p/2. - Note that due to network and processing delays the the period - of tracing is approximate. - The example below shows how to set up a trace which will be - automatically stopped and formatted after 5 seconds -

-(tiger@durin)1>ttb:start_trace([node()], - [{erlang, now,[]}], - {all, call}, - [{timer, {5000, format}}]). - + milliseconds using + ttb:stop/0. If more + options are provided (TimerSpec = {MSec, Opts}), + ttb:stop/1 + is called instead with Opts as argument.

+

The timer is started with + ttb:p/2, so any trace patterns + must be set up in advance. + ttb:start_trace/4 + always sets up all patterns before invoking ttb:p/2.

+

The following example shows how to set up a trace that is + automatically stopped and formatted after 5 seconds: + 

+(tiger@durin)1> ttb:start_trace([node()],
+                                [{erlang, now,[]}],
+                                {all, call},
+                                [{timer, {5000, format}}]).
+

Because of network and processing delays, the period + of tracing is approximate.

 +
- Overload protection -

When tracing live systems, special care needs to be always taken - not to overload a node with too heavy tracing. ttb provides - the overload option to help to address the problem.

-

{overload, MSec, Module, Function} instructs the ttb backend - (called observer_backend, part of the runtime_tools - application) to perform overload check every MSec milliseconds. - If the check (namely Module:Function(check)) returns + Overload Protection +

When tracing live systems, always take special care to not + overload a node with too heavy tracing. ttb provides + option overload to address this problem.

+

{overload, MSec, Module, Function} instructs the ttb back end + (a part of the Runtime_Tools + application) to perform overload check every MSec millisecond. + If the check (named Module:Function(check)) returns true, tracing is disabled on the selected node.

Overload protection activated on one node does not affect other nodes, where the tracing continues as normal. - ttb:stop/0/1 fetches data from all clients, including everything - that has been collected before overload protection was activated. - Note that - changing trace details (with ttb:p and ttb:tp/tpl...) - once overload protection gets activated in one of the traced - nodes is not permitted in order not to allow trace setup - to be inconsistent between nodes. -

-

Module:Function provided with the overload option must - handle three calls: init, check and stop. init - and stop allows to perform some setup and teardown required by - the check. An overload check module could look like this (note that - check is always called by the same process, so put and - get are possible). -

+ ttb:stop/0,1 fetches data from all clients, including everything + collected before the activation of overload protection.

+ +

+ It is not allowed to change trace details + (with ttb:p and ttb:tp/tpl...) once overload + protection is activated in one of the traced nodes. This is to + avoid trace setup being inconsistent between nodes.

 + +

Module:Function provided with option overload must + handle three calls: init, check, and stop. init + and stop allow some setup and teardown required by + the check. An overload check module can look as follows: +

-module(overload). -export([check/1]). @@ -362,33 +372,37 @@ check(check) -> end; check(stop) -> get(pid) ! stop. +

+ check is always called by the same process, so put and + get are possible.
Autoresume -

It is possible that a node (probably a buggy one, hence traced) - crashes. In order to automatically resume tracing on the node - as soon as it gets back, resume has to be used. When - it is, the failing node tries to reconnect - to trace control node as soon as runtime tools is started. - This implies that runtime_tools must be included in - other node's startup chain (if it is not, one could still - resume tracing by starting runtime_tools manually, - i.e. by an RPC call).

-

In order not to loose the data that the failing node stored - up to the point of crash, the control node will try to fetch - it before restarting trace. This must happen within the allowed - time frame or is aborted (default is 10 seconds, can be customized with - {resume, MSec}). The data fetched this way is then - merged with all other traces.

-

Autostart feature requires additional data to be stored on +

A node can crash (probably a buggy one, hence traced). + Use resume to resume tracing on the node automatically + when it gets back. The failing node then tries to reconnect + to trace control node when Runtime_Tools is started. + This implies that Runtime_Tools must be included in + the startup chain of other nodes (if not, you can still + resume tracing by starting Runtime_Tools manually, + that is, by an RPC call).

+

To not lose the data that the failing node stored + up to the point of crash, the control node tries to fetch + it before restarting trace. This must occur within the allowed + time frame, otherwise it is aborted (default is 10 seconds, but it + can be changed with {resume, MSec}). The data fetched + this way is then merged with all other traces.

+

The autostart feature requires more data to be stored on traced nodes. By default, the data is stored automatically - to the file called "ttb_autostart.bin" in the traced node's cwd. - Users may decide to change this behaviour (i.e. on diskless + to the file named "ttb_autostart.bin" in the currect working directory + (cwd) of the traced node. + Users can change this behaviour (that is, on diskless nodes) by specifying their own module to handle autostart data storage and retrieval (ttb_autostart_module - environment variable of runtime_tools). Please see the - ttb's reference manual to see the module's API. This example - shows the default handler

+ environment variable of runtime_tools). For information + about the API, see module + ttb. + The following example shows the default handler:

-module(ttb_autostart). -export([read_config/0, @@ -407,54 +421,60 @@ read_config() -> end. write_config(Data) -> - file:write_file(?AUTOSTART_FILENAME, term_to_binary(Data)). - -

Remember that file trace ports buffer the data + file:write_file(?AUTOSTART_FILENAME, term_to_binary(Data)). + +

Remember that file trace ports buffer the data by default. If the node crashes, trace messages are not - flushed to the binary log. If the chance of failure is - high, it might be a good idea to automatically flush - the buffers every now and then. Passing {flush, MSec} - as one of ttb:tracer/2 option flushes all buffers - every MSec milliseconds.

+ flushed to the binary log. If the risk of failure is + high, it can be a good idea to flush the buffers every + now and then automatically. Passing {flush, MSec} + as an option of ttb:tracer/2 flushes all buffers + every MSec millisecond.

- dbg mode -

The {shell, ShellType} option allows to make ttb - operation similar to dbg. Using {shell, true} + dbg Mode +

Option {shell, ShellType} allows making ttb + operation similar to + dbg. + Using {shell, true} displays all trace messages in the shell before storing them. {shell, only} additionally disables message storage - (so that the tool behaves exactly like dbg). This is allowed - only with ip trace ports ({trace, {local, File}}). + (making the tool to behave exactly like dbg). This is + allowed only with IP trace ports ({trace, {local, File}}).

-

The command ttb:tracer(dbg) is a shortcut for the pure-dbg - mode ({shell, only}).

+

Command ttb:tracer(dbg) is a shortcut for the pure + dbg mode ({shell, only}).

- Trace Information and the .ti File -

In addition to the trace log file(s), a file with the extension - .ti is created when the Trace Tool Builder is started. This - is the trace information file. It is a binary file, and it + Trace Information and File .ti +

In addition to the trace log file(s), a file with extension + .ti is created when Trace Tool Builder is started. This + is the trace information file. It is a binary file, which contains the process information, trace flags used, the name of - the node to which it belongs and all information written with the - write_trace_info/2 function. .ti files are always fetched - with other logs when the trace is stopped. + the node to which it belongs, and all information written with + function + ttb:write_trace_info/2. + .ti files are always fetched with other logs when the trace is stopped.

Except for the process information, everything in the trace information file is passed on to the handler function when - formatting. The TI parameter is a list of + formatting. Parameter TI is a list of {Key,ValueList} tuples. The keys flags, - handler, file and node are used for + handler, file, and node are used for information written directly by ttb.

-

You can add information to the trace information file by - calling write_trace_info/2. Note that ValueList - always will be a list, and if you call write_trace_info/2 - several times with the same Key, the ValueList will - be extended with a new value each time. Example: +

Information to the trace information file by + can be added by calling + ttb:write_trace_info/2. + Notice that ValueList + always is a list, and if you call write_trace_info/2 + many times with the same Key, the ValueList is + extended with a new value each time.

+

Example:

ttb:write_trace_info(mykey,1) gives the entry {mykey,[1]} in TI. Another call, ttb:write_trace_info(mykey,2), changes this entry to @@ -467,15 +487,15 @@ write_config(Data) ->

If you want to limit the size of the trace logs, you can use wrap logs. This works almost like a circular buffer. You can specify the maximum number of binary logs and the maximum size of - each log. ttb will create a new binary log each time a log - reaches the maximum size. When the the maximum number of logs are + each log. ttb then creates a new binary log each time a log + reaches the maximum size. When the maximum number of logs are reached, the oldest log is deleted before a new one is created.

-

Note that the overall size of data generated by ttb may be greater - than the wrap specification would suggest - if a traced node restarts - and autoresume is enabled, old wrap log is always stored and +

The overall size of data generated by ttb can be greater + than the wrap specification suggests. If a traced node restarts + and autoresume is enabled, the old wrap log is always stored and a new one is created. -

+

Wrap logs can be formatted one by one or all at once. See Formatting.

@@ -485,52 +505,61 @@ write_config(Data) -> Formatting

Formatting can be done automatically when stopping ttb - (see Automatically collect and format logs from all nodes), or explicitly by calling - the ttb:format/1/2 function. + (see section + Automatically Collect and Format Logs from All Nodes), or explicitly by calling function + ttb:format/1,2.

Formatting means to read a binary log and present it in a readable format. You can use the default format handler in ttb to present each trace message as a line of text, or write your own handler to make more complex interpretations of the - trace information. You can even use the Event Tracer et to - present the trace log graphically (see Presenting trace logs with Event Tracer). + trace information. You can also use application ET to + present the trace log graphically (see section + Presenting Trace Logs with Event Tracer).

-

The first argument to ttb:format/1/2 specifies which +

The first argument to ttb:format/1,2 specifies which binary log(s) to format. This is usually the name of a directory - that ttb created during log fetch. Unless there is the disable_sort - option provided, the logs from different files are always sorted - according to timestamp in traces. + that ttb created during log fetch. Unless option + disable_sort is provided, the logs from different files + are always sorted according to time-stamp in traces.

The second argument to ttb:format/2 is a list of - options. The out option specifies the destination where the - formatted text shall be written. Default destination is - standard_io, but a filename can also be given. The - handler option specifies the format handler to use. If this - option is not given, the handler option given when starting - the tracer is used. If the handler option was not given - when starting the tracer either, a default handler is used, which - prints each trace message as a line of text. The disable_sort - option indicates that there logs should not be merged according to - timestamp, but processed one file after another (this might be - a bit faster). + options as follows:

-

A format handler is a fun taking four arguments. This fun will - be called for each trace message in the binary log(s). A simple - example which only prints each trace message could be like this:

+ + out +

Specifies the destination to write the formatted text. + Default destination is standard_io, but a filename can + also be specified.

 + handler +

Specifies the format handler to use. If this option is + not specified, option handler that is specified when starting + the tracer is used. If option handler is not specified + when starting the tracer either, a default handler is used, which + prints each trace message as a text line.

 + disable_sort +

Indicates that the logs are not to be merged according to + time-stamp, but processed one file after another (this can be + a bit faster).

 + +

A format handler is a fun taking four arguments. This fun is + called for each trace message in the binary log(s). A simple + example that only prints each trace message can be as follows:

fun(Fd, Trace, _TraceInfo, State) -> io:format(Fd, "Trace: ~p~n", [Trace]), State end. -

Fd is the file descriptor for the destination file, or +

Here, Fd is the file descriptor for the destination file, or the atom standard_io. _TraceInfo contains information - from the trace information file (see Trace Information and the .ti File). State is a state variable for the format - handler fun. The initial value of the State variable is - given with the handler option, e.g.

+ from the trace information file (see section + Trace Information and File .ti). State is a state variable for the format + handler fun. The initial value of variable State is + specified with the handler option, for example:

ttb:format("tiger@durin-ttb", [{handler, {{Mod,Fun}, initial_state}}]) ^^^^^^^^^^^^^ -

Another format handler could be used to calculate time spent by +

Another format handler can be used to calculate the time spent by the garbage collector:

fun(_Fd,{trace_ts,P,gc_start,_Info,StartTs},_TraceInfo,State) -> @@ -541,111 +570,118 @@ fun(_Fd,{trace_ts,P,gc_start,_Info,StartTs},_TraceInfo,State) -> io:format("GC in process ~w: ~w milliseconds~n", [P,Time]), State -- [{P,StartTs}] end -

A more refined version of this format handler is the function - handle_gc/4 in the module multitrace.erl which can - be found in the src directory of the Observer application. +

A more refined version of this format handler is function + handle_gc/4 in module multitrace.erl + included in directory src of the Observer application.

-

The actual trace message is passed as the second argument (Trace). - The possible values of Trace are:

+

The trace message is passed as the second argument (Trace). + The possible values of Trace are the following:

- all trace messages described in erlang:trace/3 documentation, + All trace messages described in + erlang:trace/3 - {drop, N} if ip tracer is used (see dbg:trace_port/2), + {drop, N} if IP tracer is used (see + dbg:trace_port/2) - end_of_trace received once when all trace messages have - been processed. + end_of_trace received once when all trace messages are + processed -

By giving the format handler ttb:get_et_handler(), you can have the trace - log presented graphically with et_viewer in the Event - Tracer application (see Presenting trace logs with Event Tracer). +

By giving the format handler + ttb:get_et_handler(), + you can have the trace + log presented graphically with et_viewer in the ET + application (see section + Presenting Trace Logs with Event Tracer).

-

You may always decide not to format the whole trace data contained - in the fetch directory, but analyze single files instead. In order - to do so, a single file (or list of files) have to be passed as - the first argument to format/1/2.

-

Wrap logs can be formatted one by one or all in one go. To - format one of the wrap logs in a set, give the exact name of the - file. To format the whole set of wrap logs, give the name with '*' - instead of the wrap count. An example: +

You can always decide not to format the whole trace data contained + in the fetch directory, but analyze single files instead. To do so, + a single file (or list of files) must be passed as the first argument + to format/1,2.

+

Wrap logs can be formatted one by one or all at once. To + format one of the wrap logs in a set, specify the exact file name. + To format the whole set of wrap logs, specify the name with * + instead of the wrap count.

+

Example:

Start tracing:

- -(tiger@durin)1> ttb:tracer(node(),{file,{wrap,"trace"}}). + 
+(tiger@durin)1> ttb:tracer(node(),{file,{wrap,"trace"}}).
 {ok,[tiger@durin]}
-(tiger@durin)2> ttb:p(...)
-...    
-    
This will give a set of binary logs, like:

+(tiger@durin)2> ttb:p(...)
+...
+

This gives a set of binary logs, for example:

tiger@durin-trace.0.wrp tiger@durin-trace.1.wrp tiger@durin-trace.2.wrp ...

Format the whole set of logs:

- -1> ttb:format("tiger@durin-trace.*.wrp"). + 
+1> ttb:format("tiger@durin-trace.*.wrp").
 ....
 ok
-2>    
+2>

Format only the first log:

- -1> ttb:format("tiger@durin-trace.0.wrp"). + 
+1> ttb:format("tiger@durin-trace.0.wrp").
 ....
 ok
-2>    
+2>

To merge all wrap logs from two nodes:

- -1> ttb:format(["tiger@durin-trace.*.wrp","lion@durin-trace.*.wrp"]). + 
+1> ttb:format(["tiger@durin-trace.*.wrp","lion@durin-trace.*.wrp"]).
 ....
 ok
-2>    
+2>
- Presenting trace logs with Event Tracer -

For detailed information about the Event Tracer, please turn - to the User's Guide and Reference Manuals for the et - application. + Presenting Trace Logs with Event Tracer +

For detailed information about the Event Tracer, see the + ET application.

-

By giving the format handler ttb:get_et_handler(), you can have the - trace log presented graphically with et_viewer in the - Event Tracer application. ttb provides a few different - filters which can be selected from the Filter menu in the - et_viewer window. The filters are names according to the - type of actors they present (i.e. what each vertical line in the - sequence diagram represent). Interaction between actors is shown - as red arrows between two vertical lines, and activities within - an actor are shown as blue text to the right of the actors line. +

By giving the format handler + ttb:get_et_handler(), + you can have the trace log presented graphically with + et_viewer in the ET application. + ttb provides filters that can be selected from the + menu Filter in the et_viewer window. The filters + are names according to the type of actors they present + (that is, what each vertical line in the sequence diagram represents). + Interaction between actors is shown as red arrows between two + vertical lines, and activities within an actor are shown as + blue text to the right of the actors line.

-

The processes filter is the only filter which will - show all trace messages from a trace log. Each vertical line in +

The processes filter is the only filter showing all + trace messages from a trace log. Each vertical line in the sequence diagram represents a process. Erlang messages, - spawn and link/unlink are typical interactions between - processes. Function calls, scheduling and garbage collection are - typical activities within a process. processes is the - default filter. + spawn, and link/unlink are typical interactions between + processes. Function calls, scheduling, and garbage collection, + are typical activities within a process. processes is + the default filter.

-

The rest of the filters will only show function calls and +

The remaining filters only show function calls and function returns. All other trace message are discarded. To get - the most out of these filters, et_viewer needs to known + the most out of these filters, et_viewer must know the caller of each function and the time of return. This can be - obtained by using both the call and return_to - flags when tracing. Note that the return_to flag only - works with local call trace, i.e. when trace patterns are set + obtained using both the call and return_to + flags when tracing. Notice that flag return_to only + works with local call trace, that is, when trace patterns are set with ttb:tpl.

-

The same result can be obtained by using the call flag - only and setting a match specification like this on local or - global function calls:

- -1> dbg:fun2ms(fun(_) -> return_trace(),message(caller()) end). -[{'_',[],[{return_trace},{message,{caller}}]}] -

This should however be done with care, since the - {return_trace} function in the match specification will - destroy tail recursiveness. +

The same result can be obtained by using the flag call + only and setting a match specification on local or + global function calls as follows:

+ 
+1> dbg:fun2ms(fun(_) -> return_trace(),message(caller()) end).
+[{'_',[],[{return_trace},{message,{caller}}]}]
+

This must however be done with care, as function + {return_trace} in the match specification + destroys tail recursiveness.

The modules filter shows each module as a vertical line in the sequence diagram. External function calls/returns - are shown as interactions between modules and internal function + are shown as interactions between modules, and internal function calls/returns are shown as activities within a module.

The functions filter shows each function as a vertical @@ -656,9 +692,9 @@ ok

The mods_and_procs and funcs_and_procs filters are equivalent to the modules and functions filters respectively, except that each module or function can - have several vertical lines, one for each process it resides on. + have many vertical lines, one for each process it resides on.

-

In the next example, modules foo and bar are used:

+

In the following example, modules foo and bar are used:

-module(foo). -export([start/0,go/0]). @@ -673,8 +709,9 @@ go() -> go -> bar:f1(), go() - end. - + end. + + -module(bar). -export([f1/0,f3/0]). f1() -> @@ -685,57 +722,56 @@ f2() -> f3() -> ok. -

Now let's set up the trace.

- -(tiger@durin)1>%%First we retrieve the Pid to limit traced processes set -(tiger@durin)1>Pid = foo:start(). -(tiger@durin)2>%%Now we set up tracing -(tiger@durin)2>ttb:tracer(). -(tiger@durin)3>ttb:p(Pid, [call, return_to, procs, set_on_spawn]). -(tiger@durin)4>ttb:tpl(bar, []). -(tiger@durin)5>%%Invoke our test function and see output with et viewer -(tiger@durin)5>Pid ! go. -(tiger@durin)6>ttb:stop({format, {handler, ttb:get_et_handler()}}). - - -

This should render a result similar to the - following: +

Setting up the trace:

+
+(tiger@durin)1> %%First we retrieve the Pid to limit traced processes set
+(tiger@durin)1> Pid = foo:start().
+(tiger@durin)2> %%Now we set up tracing
+(tiger@durin)2> ttb:tracer().
+(tiger@durin)3> ttb:p(Pid, [call, return_to, procs, set_on_spawn]).
+(tiger@durin)4> ttb:tpl(bar, []).
+(tiger@durin)5> %%Invoke our test function and see output with et viewer
+(tiger@durin)5> Pid ! go.
+(tiger@durin)6> ttb:stop({format, {handler, ttb:get_et_handler()}}).
+ +

This renders a result similar to the following:

-

Filter: "processes" +

Filter: "mods_and_procs" -

Note, that we can use ttb:start_trace/4 function to help - us here:

- -(tiger@durin)1>Pid = foo:start(). -(tiger@durin)2>ttb:start_trace([node()], - [{bar,[]}], - {Pid, [call, return_to, procs, set_on_spawn]} - {handler, ttb:get_et_handler()}). -(tiger@durin)3>Pid ! go. -(tiger@durin)4>ttb:stop(format). - +

Notice that function + ttb:start_trace/4 + can be used as help as follows:

+
+(tiger@durin)1> Pid = foo:start().
+(tiger@durin)2> ttb:start_trace([node()],
+                                [{bar,[]}],
+                                {Pid, [call, return_to, procs, set_on_spawn]}
+                                {handler, ttb:get_et_handler()}).
+(tiger@durin)3> Pid ! go.
+(tiger@durin)4> ttb:stop(format).
- Automatically collect and format logs from all nodes -

By default ttb:stop/1 fetches trace logs and - trace information files from all nodes. The logs are stored in a - new directory named ttb_upload-Filename-Timestamp under the working - directory of the trace control node. Fetching may be disabled by - providing the nofetch option to ttb:stop/1. User can - specify a fetch directory of his choice passing the - {fetch_dir, Dir} option. + Automatically Collect and Format Logs from All Nodes +

By default, + + ttb:stop/1 fetches trace logs + and trace information files from all nodes. The logs are stored in a + new directory named ttb_upload-Filename-Timestamp under the + working directory of the trace control node. Fetching can be disabled + by providing option nofetch to ttb:stop/1. The user can + specify a fetch directory by passing option {fetch_dir, Dir}.

-

If the option format is given to ttb:stop/1, the +

If option format is specified to ttb:stop/1, the trace logs are automatically formatted after tracing is stopped.

@@ -743,116 +779,122 @@ f3() ->
History and Configuration Files -

For the tracing functionality, dbg could be used instead - of the ttb for setting trace flags on processes and trace - patterns for call trace, i.e. the functions p, tp, - tpl, ctp, ctpl and ctpg. There are only - two things added by ttb for these functions:

+

For the tracing functionality, + dbg + can be used instead + of ttb for setting trace flags on processes and trace + patterns for call trace, that is, the functions + p, tp, tpl, ctp, ctpl, and ctpg. Only the + following two things are added by ttb for these functions:

- all calls are stored in the history buffer and can be + All calls are stored in the history buffer and can be recalled and stored in a configuration file. This makes it - easy to setup the same trace environment e.g. if you want to - compare two test runs. It also reduces the amount of - typing when using ttb from the erlang shell; - shortcuts are provided for the most common match - specifications (in order not to force the user to use - dbg:fun2ms continually). + easy to set up the same trace environment, for example, if you + want to compare two test runs. It also reduces the amount of + typing when using ttb from the Erlang shell. + Shortcuts are provided for the most common match + specifications (to not force you to use + dbg:fun2ms + continually). -

Use list_history/0 to see the content of the history - buffer, and run_history/1 to re-execute one of the entries. +

Use + ttb:list_history/0 + to see the content of the history buffer and + ttb:run_history/1 + to re-execute one of the entries.

The main purpose of the history buffer is the possibility to create configuration files. Any function stored in the history buffer can be written to a configuration file and used for - creating a specific configuration at any time with one single + creating a specific configuration at any time with a single function call.

A configuration file is created or extended with - write_config/2/3. Configuration files are binary files + ttb:write_config/2,3. + Configuration files are binary files and can therefore only be read and written with functions provided by ttb.

-

You can write the complete content of the history buffer to a - config file by calling - ttb:write_config(ConfigFile,all). And you can write - selected entries from the history by calling +

The complete content of the history buffer can be written to a + configuration file by calling + ttb:write_config(ConfigFile,all). Selected entries from + the history can be written by calling ttb:write_config(ConfigFile,NumList), where NumList is a list of integers pointing out the history entries to write. Moreover, the history buffer is always dumped - to ttb_last_config when ttb:stop/0/1 is called. + to ttb_last_config when ttb:stop/0,1 is called.

-

User defined entries can also be written to a config file by - calling the function - ttb:write_config(ConfigFile,ConfigList) where +

User-defined entries can also be written to a configuration file + by calling function + ttb:write_config(ConfigFile,ConfigList), where ConfigList is a list of {Module,Function,Args}.

Any existing file ConfigFile is deleted and a new file - is created when write_config/2 is called. The option - append can be used if you wish to add something at the end - of an existing config file, e.g. + is created when write_config/2 is called. Option + append can be used to add something at the end + of an existing configuration file, for example, ttb:write_config(ConfigFile,What,[append]).

-
- Example: History and configuration files -

See the content of the history buffer

- ttb:tracer(). +

Example:

+

See the content of the history buffer:

+ 
+(tiger@durin)191> ttb:tracer().
 {ok,[tiger@durin]}
-(tiger@durin)192> ttb:p(self(),[garbage_collection,call]).               
-{ok,{[<0.1244.0>],[garbage_collection,call]}}
-(tiger@durin)193> ttb:tp(ets,new,2,[]).                                  
+(tiger@durin)192> ttb:p(self(),[garbage_collection,call]).
+{ok,{[<0.1244.0>],[garbage_collection,call]}}
+(tiger@durin)193> ttb:tp(ets,new,2,[]).
 {ok,[{matched,1}]}
-(tiger@durin)194> ttb:list_history().
+(tiger@durin)194> ttb:list_history().
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
- {3,{ttb,tp,[ets,new,2,[]]}}]      ]]>
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {3,{ttb,tp,[ets,new,2,[]]}}]

Execute an entry from the history buffer:

- ttb:ctp(ets,new,2). + 
+(tiger@durin)195> ttb:ctp(ets,new,2).
 {ok,[{matched,1}]}
-(tiger@durin)196> ttb:list_history().
+(tiger@durin)196> ttb:list_history().
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
  {3,{ttb,tp,[ets,new,2,[]]}},
  {4,{ttb,ctp,[ets,new,2]}}]
-(tiger@durin)197> ttb:run_history(3).
+(tiger@durin)197> ttb:run_history(3).
 ttb:tp(ets,new,2,[]) ->
-{ok,[{matched,1}]}      ]]>
+{ok,[{matched,1}]}

Write the content of the history buffer to a configuration file:

- ttb:write_config("myconfig",all). + 
+(tiger@durin)198> ttb:write_config("myconfig",all).
 ok
-(tiger@durin)199> ttb:list_config("myconfig").
+(tiger@durin)199> ttb:list_config("myconfig").
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
  {3,{ttb,tp,[ets,new,2,[]]}},
  {4,{ttb,ctp,[ets,new,2]}},
- {5,{ttb,tp,[ets,new,2,[]]}}]      ]]>
+ {5,{ttb,tp,[ets,new,2,[]]}}]

Extend an existing configuration:

- ttb:write_config("myconfig",[{ttb,tp,[ets,delete,1,[]]}], -[append]). + 
+(tiger@durin)200> ttb:write_config("myconfig",[{ttb,tp,[ets,delete,1,[]]}],
+[append]).
 ok
-(tiger@durin)201> ttb:list_config("myconfig").
+(tiger@durin)201> ttb:list_config("myconfig").
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
  {3,{ttb,tp,[ets,new,2,[]]}},
  {4,{ttb,ctp,[ets,new,2]}},
  {5,{ttb,tp,[ets,new,2,[]]}},
- {6,{ttb,tp,[ets,delete,1,[]]}}]      ]]>
+ {6,{ttb,tp,[ets,delete,1,[]]}}]

Go back to a previous configuration after stopping Trace Tool Builder:

- ttb:stop(). + 
+(tiger@durin)202> ttb:stop().
 ok
-(tiger@durin)203> ttb:run_config("myconfig").
+(tiger@durin)203> ttb:run_config("myconfig").
 ttb:tracer(tiger@durin,[]) ->
 {ok,[tiger@durin]}
 
-ttb:p(<0.1244.0>,[garbage_collection,call]) ->
-{ok,{[<0.1244.0>],[garbage_collection,call]}}
+ttb:p(<0.1244.0>,[garbage_collection,call]) ->
+{ok,{[<0.1244.0>],[garbage_collection,call]}}
 
 ttb:tp(ets,new,2,[]) ->
 {ok,[{matched,1}]}
@@ -866,133 +908,135 @@ ttb:tp(ets,new,2,[]) ->
 ttb:tp(ets,delete,1,[]) ->
 {ok,[{matched,1}]}
 
-ok      ]]>
+ok

Write selected entries from the history buffer to a configuration file:

- ttb:list_history(). + 
+(tiger@durin)204> ttb:list_history().
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
  {3,{ttb,tp,[ets,new,2,[]]}},
  {4,{ttb,ctp,[ets,new,2]}},
  {5,{ttb,tp,[ets,new,2,[]]}},
  {6,{ttb,tp,[ets,delete,1,[]]}}]
-(tiger@durin)205> ttb:write_config("myconfig",[1,2,3,6]).
+(tiger@durin)205> ttb:write_config("myconfig",[1,2,3,6]).
 ok
-(tiger@durin)206> ttb:list_config("myconfig").
+(tiger@durin)206> ttb:list_config("myconfig").
 [{1,{ttb,tracer,[tiger@durin,[]]}},
- {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
+ {2,{ttb,p,[<0.1244.0>,[garbage_collection,call]]}},
  {3,{ttb,tp,[ets,new,2,[]]}},
  {4,{ttb,tp,[ets,delete,1,[]]}}]
-(tiger@durin)207>       ]]>
-
+(tiger@durin)207>
Sequential Tracing

To learn what sequential tracing is and how it can be used, - please turn to the reference manual for the - seq_trace module in the kernel - application. + see the Reference Manual for + seq_trace.

-

The support for sequential tracing provided by the Trace Tool - Builder includes

+

The support for sequential tracing provided by Trace Tool + Builder includes the following:

Initiation of the system tracer. This is automatically - done when a trace port is started with ttb:tracer/0/1/2 - Creation of match specifications which activates - sequential tracing + done when a trace port is started with + ttb:tracer/0,1,2. + Creation of match specifications that activates + sequential tracing. -

Starting sequential tracing requires that a tracer has been - started with the ttb:tracer/0/1/2 function. Sequential - tracing can then either be started via a trigger function with a - match specification created with ttb:seq_trigger_ms/0/1, - or directly by using the seq_trace module in the - kernel application. +

Starting sequential tracing requires that a tracer is + started with function ttb:tracer/0,1,2. Sequential + tracing can then be started in either of the following ways:

+ + Through a trigger function with a match specification + created with + ttb:seq_trigger_ms/0,1. + Directly by using module + seq_trace. + -
- Example: Sequential tracing -

In the following example, the function +

Example 1:

+

In the following example, function dbg:get_tracer/0 is used as trigger for sequential tracing:

- ttb:tracer(). + 
+(tiger@durin)110> ttb:tracer().
 {ok,[tiger@durin]}
-(tiger@durin)111> ttb:p(self(),call).                               
-{ok,{[<0.158.0>],[call]}}
-(tiger@durin)112> ttb:tp(dbg,get_tracer,0,ttb:seq_trigger_ms(send)).
+(tiger@durin)111> ttb:p(self(),call).
+{ok,{[<0.158.0>],[call]}}
+(tiger@durin)112> ttb:tp(dbg,get_tracer,0,ttb:seq_trigger_ms(send)).
 {ok,[{matched,1},{saved,1}]}
-(tiger@durin)113> dbg:get_tracer(), seq_trace:reset_trace().         
+(tiger@durin)113> dbg:get_tracer(), seq_trace:reset_trace().
 true
-(tiger@durin)114> ttb:stop(format).
-({<0.158.0>,{shell,evaluator,3},tiger@durin}) call dbg:get_tracer()
-SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin}) 
-{<0.237.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}} 
+(tiger@durin)114> ttb:stop(format).
+({<0.158.0>,{shell,evaluator,3},tiger@durin}) call dbg:get_tracer()
+SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin})
+{<0.237.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}}
 [Serial: {0,1}]
-SeqTrace [0]: ({<0.237.0>,dbg,tiger@durin}) 
-{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.222>}} 
+SeqTrace [0]: ({<0.237.0>,dbg,tiger@durin})
+{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.222>}}
 [Serial: {1,2}]
 ok
-(tiger@durin)116>       ]]>
-      
Starting sequential tracing with a trigger is actually more
+(tiger@durin)116>
+

Example 2:

+

Starting sequential tracing with a trigger is more useful if the trigger function is not called directly from the shell, but rather implicitly within a larger system. When calling a function from the shell, it is simpler to start - sequential tracing directly, e.g.

- ttb:tracer(). + sequential tracing directly, for example, as follows:

+ 
+(tiger@durin)116> ttb:tracer().
 {ok,[tiger@durin]}
-(tiger@durin)117> seq_trace:set_token(send,true), dbg:get_tracer(), 
-seq_trace:reset_trace().
+(tiger@durin)117> seq_trace:set_token(send,true), dbg:get_tracer(),
+seq_trace:reset_trace().
 true
-(tiger@durin)118> ttb:stop(format).
-SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin}) 
-{<0.246.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}} 
+(tiger@durin)118> ttb:stop(format).
+SeqTrace [0]: ({<0.158.0>,{shell,evaluator,3},tiger@durin})
+{<0.246.0>,dbg,tiger@durin} ! {<0.158.0>,{get_tracer,tiger@durin}}
 [Serial: {0,1}]
-SeqTrace [0]: ({<0.246.0>,dbg,tiger@durin}) 
-{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.229>}} 
+SeqTrace [0]: ({<0.246.0>,dbg,tiger@durin})
+{<0.158.0>,{shell,evaluator,3},tiger@durin} ! {dbg,{ok,#Port<0.229>}}
 [Serial: {1,2}]
 ok
-(tiger@durin)120>       ]]>
-      
In both examples above, the seq_trace:reset_trace/0
-        resets the trace token immediately after the traced function in
-        order to avoid lots of trace messages due to the printouts in
-        the erlang shell.
+(tiger@durin)120>
+

In both previous examples, seq_trace:reset_trace/0 + resets the trace token immediately after the traced function + to avoid many trace messages because of the printouts in + the Erlang shell.

-

All functions in the seq_trace module, except - set_system_tracer/1, can be used after the trace port has - been started with ttb:tracer/0/1/2. +

All functions in module seq_trace, except + set_system_tracer/1, can be used after the trace port + is started with ttb:tracer/0,1,2.

-
- Example: Multipurpose trace tool -

The module multitrace.erl which can be found in the - src directory of the Observer application implements a + Multipurpose Trace Tool +

Module multitrace in + directory src of the Observer application provides a small tool with three possible trace settings. The trace messages - are written to binary files which can be formatted with the - function multitrace:format/1/2. + are written to binary files, which can be formatted with + function multitrace:format/1,2:

- multitrace:debug(What) - Start calltrace on all processes and trace the given + multitrace:debug(What) +

Start calltrace on all processes and trace the specified function(s). The format handler used is - multitrace:handle_debug/4 which prints each call and - return. What must be an item or a list of items to trace, - given on the format {Module,Function,Arity}, - {Module,Function} or just Module. - multitrace:gc(Procs) - Trace garbage collection on the given process(es). The - format handler used is multitrace:handle_gc/4 which - prints start and stop and the time spent for each GC. - multitrace:schedule(Procs) - Trace in- and out-scheduling on the given process(es). The - format handler used is multitrace:handle_schedule/4 which - prints each in and out scheduling with process, timestamp and + multitrace:handle_debug/4 that prints each call and + returns. What must be an item or a list of items to trace, + specified on the format {Module,Function,Arity}, + {Module,Function}, or only Module.

 + multitrace:gc(Procs) +

Trace garbage collection on the specified process(es). The + format handler used is multitrace:handle_gc/4 that + prints start, stop, and the time spent for each garbage collection.

 + multitrace:schedule(Procs) +

Trace in-scheduling and out-scheduling on the specified process(es). + The format handler used is multitrace:handle_schedule/4 that + prints each in-scheduling and out-scheduling with process, time-stamp, and current function. It also prints the total time each traced - process was scheduled in. + process was scheduled in.
-- cgit v1.2.3 From 2a43b90eadcbce8763c84d2692e89f5e7a1ec150 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Mon, 14 Dec 2015 10:01:25 +0100 Subject: debugger: Editorial changes in documentation --- lib/debugger/doc/src/book.xml | 1 - lib/debugger/doc/src/debugger.xml | 26 +- lib/debugger/doc/src/debugger_chapter.xml | 858 +++++++++++++++--------------- lib/debugger/doc/src/i.xml | 138 +++-- lib/debugger/doc/src/int.xml | 334 ++++++------ lib/debugger/doc/src/introduction.xml | 63 +++ lib/debugger/doc/src/part.xml | 12 +- lib/debugger/doc/src/ref_man.xml | 7 +- 8 files changed, 743 insertions(+), 696 deletions(-) create mode 100644 lib/debugger/doc/src/introduction.xml diff --git a/lib/debugger/doc/src/book.xml b/lib/debugger/doc/src/book.xml index 071a04eb61..5424ef2c04 100644 --- a/lib/debugger/doc/src/book.xml +++ b/lib/debugger/doc/src/book.xml @@ -47,4 +47,3 @@ - diff --git a/lib/debugger/doc/src/debugger.xml b/lib/debugger/doc/src/debugger.xml index 15d498d5ae..1ecdbcd064 100644 --- a/lib/debugger/doc/src/debugger.xml +++ b/lib/debugger/doc/src/debugger.xml @@ -4,7 +4,7 @@
- 20022013 + 20022016 Ericsson AB. All Rights Reserved. @@ -29,7 +29,7 @@
debugger - Erlang Debugger + Erlang Debugger.

Erlang Debugger for debugging and testing of Erlang programs.

 @@ -48,14 +48,14 @@

Starts Debugger.

-

If given a file name as argument, Debugger will try to load - its settings from this file. Refer to Debugger User's Guide - for more information about settings.

+

If a filename is specified as argument, Debugger tries to load + its settings from this file. For details about settings, see + the User's Guide.

-

If given local as argument, Debugger will interpret - code only at the current node. If given global as - argument, Debugger will interpret code at all known nodes, - this is the default.

+

If local is specified as argument, Debugger interprets + code only at the current node. If global is specified as + argument, Debugger interprets code at all known nodes, this + is the default.

 @@ -67,11 +67,9 @@ Args = [term()] -

This function can be used to debug a single process. - The module Module is interpreted and - apply(Module,Name,Args) is called. This will open an - Attach Process window, refer to Debugger User's Guide for - more information.

+

Debugs a single process. The module Module is interpreted + and apply(Module,Name,Args) is called. This opens an + Attach Process window. For details, see the User's Guide.

 diff --git a/lib/debugger/doc/src/debugger_chapter.xml b/lib/debugger/doc/src/debugger_chapter.xml index 98fe4ae377..45dfdb3776 100644 --- a/lib/debugger/doc/src/debugger_chapter.xml +++ b/lib/debugger/doc/src/debugger_chapter.xml @@ -4,7 +4,7 @@
- 19972013 + 19972016 Ericsson AB. All Rights Reserved. @@ -31,97 +31,92 @@
- Introduction + Getting Started -

Debugger is a graphical user interface for the Erlang - interpreter, which can be used for debugging and testing of - Erlang programs. For example, breakpoints can be set, code can be - single stepped and variable values can be displayed and changed. -

+

To use Debugger, the basic steps are as follows:

-

The Erlang interpreter can also be accessed via the interface - module int, see int(3). -

+

Step 1. Start Debugger by calling + debugger:start().

-

Warning: Note that the Debugger at some point might - start tracing on the processes which execute the interpreted - code. This means that a conflict will occur if tracing by other - means is started on any of these processes.

-
+

The Monitor window is + displayed with information about all debugged processes, + interpreted modules, and selected options. Initially there are + normally no debugged processes. First, it must be specified which + modules that are to be debugged (also called + interpreted). Proceed as follows:

-
- Getting Started with Debugger +

Step 2. Select Module > Interpret... in the + Monitor window.

-

Start Debugger by calling debugger:start(). It will start - the Monitor window showing - information about all debugged processes, interpreted modules and - selected options.

+

The Interpret Modules window + is displayed.

-

Initially there are normally no debugged processes. First, it - must be specified which modules should be debugged, or - interpreted as it is also called. This is done by - choosing Module->Interpret... in the Monitor window and - then selecting the appropriate modules from the - Interpret Dialog window. -

+

Step 3. Select the appropriate modules from the Interpret + Dialog window.

-

Only modules compiled with the option debug_info set - can be interpreted. Non-interpretable modules are shown within - parenthesis in the Interpret Dialog window.

+

Only modules compiled with option debug_info set can be + interpreted. Non-interpretable modules are displayed within + parenthesis in the Interpret Modules window.

 -

When a module is interpreted, it can be viewed in a - View Module window. This is done - by selecting the module from the Module->module->View - menu. The contents of the source file is shown and it is possible - to set breakpoints.

- -

Now the program that should be debugged can be started. This is - done the normal way from the Erlang shell. All processes executing - code in interpreted modules will be displayed in the Monitor - window. It is possible to attach to one of these - processes, by double-clicking it, or by selecting the process and - then choosing Process->Attach.

- -

Attaching to a process will result in a - Attach Process window being - opened for this process. From the Attach Process window, it is - possible to control the process execution, inspect variable - values, set breakpoints etc.

+

Step 4. In the Monitor window, select + Module > the module to be interpreted > View.

+ +

The contents of the source file is displayed in the + View Module window.

+ +

Step 5. Set the + breakpoints, if any.

+ +

Step 6. Start the program to be debugged. This is done + the normal way from the Erlang shell.

+ +

All processes executing code in interpreted modules are displayed + in the Monitor window.

+ +

Step 7. To attach to one of these processes, + double-click it, or select the process and then choose + Process > Attach. Attaching to a process opens an + Attach Process window for this + process.

+ +

Step 8. From the Attach Process window, you can control + the process execution, inspect variable values, set breakpoints, + and so on.

- Breakpoints and Break Dialogue Windows + Breakpoints and Break Dialog Windows

Once the appropriate modules are interpreted, breakpoints can be set at relevant locations in the source code. Breakpoints are specified on a line basis. When a process reaches a breakpoint, - it stops and waits for commands (step, skip, continue,...) from - the user.

+ it stops and waits for commands (Step, Skip, + Continue ...) from the user.

When a process reaches a breakpoint, only that process is - stopped. Other processes are not affected.

+ stopped. Other processes are not affected.

 -

Breakpoints are created and deleted using the Break menu of - the Monitor window, View Module window and Attach Process window. -

+

Breakpoints are created and deleted using the Break menu of + either the Monitor window, View Module window, or Attach Process + window.

Executable Lines -

To have effect, a breakpoint must be set at an - executable line, which is a line of code containing an - executable expression such as a matching or a function call. - A blank line or a line containing a comment, function head or - pattern in a case- or receive statement is not - executable.

+

To have an effect, a breakpoint must be set at an + executable line, which is a line of code containing an + executable expression such as a matching or a function call. + A blank line or a line containing a comment, function head, or + pattern in a case statement or receive statement is not + executable.

-

In the example below, lines number 2, 4, 6, 8 and 11 are - executable lines:

+

In the following example, lines 2, 4, 6, 8, and 11 are + executable lines:

 1: is_loaded(Module,Compiled) ->
 2:   case get_file(Module,Compiled) of
@@ -141,17 +136,15 @@
       Status and Trigger Action
 
       
A breakpoint can be either active or
-	inactive. Inactive breakpoints are ignored.

-
-      
Each breakpoint has a trigger action which specifies
-	what should happen when a process has reached it (and stopped):
-      

-      
-	enable Breakpoint should remain active (default).
-	
-	disable Breakpoint should be made inactive.
-	
-	delete Breakpoint should be deleted.
+        inactive. Inactive breakpoints are ignored.

+
+      
Each breakpoint has a trigger action that specifies
+        what is to happen when a process has reached it (and stopped):

+      
+        Enable - Breakpoint is to remain active (default).
+        
+        Disable - Breakpoint is to be made inactive.
+        Delete - Breakpoint is to be deleted.
@@ -161,54 +154,56 @@

A line breakpoint is created at a certain line in a module.

- The Line Break Dialog Window. + Line Break Dialog Window -

Right-clicking the Module entry will open a popup menu from - which the appropriate module can be selected.

+

Right-click the Module entry to open a popup menu from + which the appropriate module can be selected.

-

A line breakpoint can also be created (and deleted) by - double-clicking the line when the module is displayed in - the View Module or Attach Process window.

+

A line breakpoint can also be created (and deleted) by + double-clicking the line when the module is displayed in + the View Module window or Attach Process window.

Conditional Breakpoints

A conditional breakpoint is created at a certain line in - the module, but a process reaching the breakpoint will stop - only if a given condition is true.

+ the module, but a process reaching the breakpoint stops + only if a specified condition is true.

The condition is specified by the user as a module name - CModule and a function name CFunction. When a - process reaches the breakpoint, - CModule:CFunction(Bindings) will be evaluated. If and - only if this function call returns true, the process - will stop. If the function call returns false, - the breakpoint will be silently ignored.

- -

Bindings is a list of variable bindings. Use - the function int:get_binding(Variable,Bindings) to - retrieve the value of Variable (given as an atom). - The function returns unbound or {value,Value}.

+ CModule and a function name CFunction. When a + process reaches the breakpoint, + CModule:CFunction(Bindings) is evaluated. If and + only if this function call returns true, the process + stops. If the function call returns false, + the breakpoint is silently ignored.

+ +

Bindings is a list of variable bindings. To retrieve the + value of Variable (given as an atom), use function + int:get_binding(Variable,Bindings). + The function returns unbound or {value,Value}.

- The Conditional Break Dialog Window. + Conditional Break Dialog Window -

Right-clicking the Module entry will open a popup menu from - which the appropriate module can be selected.

+

Right-click the Module entry to open a popup menu from + which the appropriate module can be selected.

-

Example: A conditional breakpoint calling - c_test:c_break/1 is added at line 6 in the module +

Example:

+ +

A conditional breakpoint calling + c_test:c_break/1 is added at line 6 in module fact. Each time the breakpoint is reached, the function is - called, and when N is equal to 3 it returns true, - and the process stops.

- + called. When N is equal to 3, the function returns + true and the process stops.

+

Extract from fact.erl:

-5.   fac(0) -> 1;
-6.   fac(N) when N > 0, is_integer(N) -> N * fac(N-1).
+5. fac(0) -> 1; +6. fac(N) when N > 0, is_integer(N) -> N * fac(N-1).

Definition of c_test:c_break/1:

@@ -228,18 +223,18 @@ c_break(Bindings) ->
       Function Breakpoints
 
       
A function breakpoint is a set of line breakpoints, one at
-	the first line of each clause in the given function.

+        the first line of each clause in the specified function.

 
       
-	The Function Break Dialog Window.
+        Function Break Dialog Window
       
 
-      
Right-clicking the Module entry will open a popup menu from
-	which the appropriate module can be selected.

+      
To open a popup menu from which the appropriate module can be
+        selected, right-click the Module entry.

 
-      
Clicking the Ok button (or 'Return' or 'Tab') when a module
-	name has been given, will bring up all functions of the module
-	in the listbox.

+      
To bring up all functions of the module in the listbox,
+        click the OK button (or press the Return
+        or Tab key) when a module name has been specified,.
@@ -249,7 +244,7 @@ c_break(Bindings) ->

The Erlang emulator keeps track of a stack trace, information about recent function calls. This information is - used, for example, if an error occurs:

+ used if an error occurs, for example:

 1> catch a+1.
 {'EXIT',{badarith,[{erlang,'+',[a,1],[]},
@@ -259,602 +254,597 @@ c_break(Bindings) ->
                    {shell,eval_exprs,7,[{file,"shell.erl"},{line,629}]},
                    {shell,eval_loop,3,[{file,"shell.erl"},{line,614}]}]}}
-

See the Erlang Reference Manual, - - Errors and Error Handling, - for more information about the stack trace.

+

For details about the stack trace, see section + Errors and Error Handling + in the Erlang Reference Manual.

-

The Debugger emulates the stack trace by keeping track of recently +

Debugger emulates the stack trace by keeping track of recently called interpreted functions. (The real stack trace cannot be - used, as it shows which functions of the Debugger have been - called, rather than which interpreted functions).

+ used, as it shows which functions of Debugger have been + called, rather than which interpreted functions.)

This information can be used to traverse the chain of function - calls, using the 'Up' and 'Down' buttons of - the Attach Process window. -

+ calls, using the Up and Down buttons in the + Attach Process window.

-

By default, the Debugger only saves information about recursive +

By default, Debugger only saves information about recursive function calls, that is, function calls that have not yet returned - a value (option 'Stack On, No Tail').

+ a value (option Stack On, No Tail).

Sometimes, however, it can be useful to save all calls, even - tail-recursive calls. That can be done with the 'Stack On, Tail' - option. Note that this option will consume more memory and slow - down execution of interpreted functions when there are many - tail-recursive calls. -

- -

It is also possible to turn off the Debugger stack trace - facility ('Stack Off'). Note: If an error occurs, in this - case the stack trace will be empty.

- -

See the section about the Monitor - Window for information about how to change the stack - trace option.

+ tail-recursive calls. This is done with option + Stack On, Tail. Notice that this option consumes more + memory and slows down execution of interpreted functions when there + are many tail-recursive calls.

+ +

To turn off the Debugger stack trace facility, select option + Stack Off.

+ + +

If an error occurs, the stack trace becomes empty in this + case.

+ + +

For information about how to change the stack trace option, see + section Monitor Window.

- The Monitor Window + Monitor Window + +

The Monitor window is the main window of Debugger and displays the + following:

-

The Monitor window is the main window of Debugger and shows a - listbox containing the names of all interpreted modules - (double-clicking a module brings up the View Module window), - which options are selected, and information about all debugged - processes, that is all processes which have been/are executing - code in interpreted modules.

+ +

A listbox containing the names of all interpreted + modules

+

Double-clicking a module brings up the View Module window.

+ +

Which options are selected

 +

Information about all debugged processes, that is, all + processes that have been or are executing code in interpreted + modules

 + - The Monitor Window. + Monitor Window -

The Auto Attach buttons, Stack Trace label, Back Trace Size - label, and Strings button show some options set, see - Options Menu for further - information about these options.

+

The Auto Attach boxes, Stack Trace label, + Back Trace Size label, and Strings box display + some options set. For details about these options, see section + Options Menu.

Process Grid - Pid

The process identifier.

 - + Initial Call

The first call to an interpreted function by this - process. (Module:Function/Arity)

 + process. (Module:Function/Arity)

Name -

The registered name, if any. If a registered name does - not show up, it may be that the Debugger received - information about the process before the name had been - registered. Try selecting Edit->Refresh.

 +

The registered name, if any. If a registered name is not + displayed, it can be that Debugger received information about + the process before the name was registered. Try selecting + Edit > Refresh.

 Status

The current status, one of the following:

idle -

The interpreted function call has returned a value, - and the process is no longer executing interpreted code. -

+

The interpreted function call has returned a value, and + the process is no longer executing interpreted code.

 running

The process is running.

 - + waiting

The process is waiting in a receive - statement.

 - + statement.

 + break

The process is stopped at a breakpoint.

 - + exit

The process has terminated.

 - + no_conn

There is no connection to the node where - the process is located.

 + the process is located.

 Information -

Additional information, if any. If the process is - stopped at a breakpoint, the field contains information - about the location {Module,Line}. If the process has - terminated, the field contains the exit reason.

 +

More information, if any. If the process is + stopped at a breakpoint, the field contains information + about the location {Module,Line}. If the process has + terminated, the field contains the exit reason.
- The File Menu - + File Menu + Load Settings... - -

Try to load and restore Debugger settings from a file - previously saved using Save Settings..., see below. - Any errors are silently ignored. - Note: Settings saved by Erlang R16B01 or later - cannot be read by Erlang R16B or earlier.

+

Tries to load and restore Debugger settings from a file + previously saved using Save Settings... (see below). + Any errors are silently ignored.

+

Notice that settings saved by Erlang/OTP R16B01 or later + cannot be read by Erlang/OTP R16B or earlier.

 - + Save Settings... -

Save Debugger settings to a file. The settings include - the set of interpreted files, breakpoints, and the selected - options. The settings can be restored in a later Debugger - session using Load Settings..., see above. - Any errors are silently ignored.

+

Saves Debugger settings to a file. The settings include + the set of interpreted files, breakpoints, and the selected + options. The settings can be restored in a later Debugger + session using Load Settings... (see above). + Any errors are silently ignored.

 - + Exit -

Stop Debugger.

 +

Stops Debugger.
- The Edit Menu + Edit Menu Refresh -

Update information about debugged processes. Removes - information about all terminated processes from the window, - and also closes all Attach Process windows for terminated - processes.

 +

Updates information about debugged processes. Information + about all terminated processes are removed from the window. All + Attach Process windows for terminated processes are closed.

 Kill All -

Terminate all processes listed in the window using - exit(Pid,kill).

 +

Terminates all processes listed in the window using + exit(Pid,kill).
- The Module Menu + Module Menu Interpret... -

Open the Interpret Dialog - window where new modules to be interpreted can - be specified.

 - +

Opens the + Interpret Modules window, + where new modules to be interpreted can be specified.

 + Delete All -

Stop interpreting all modules. Processes executing in - interpreted modules will terminate.

 +

Stops interpreting all modules. Processes executing in + interpreted modules terminate.

For each interpreted module, a corresponding entry is added to - the Module menu, with the following submenu:

+ the Module menu, with the following submenu:

Delete -

Stop interpreting the selected module. Processes - executing in this module will terminate.

 - +

Stops interpreting the selected module. Processes + executing in this module terminate.

 + View -

Open a View Module - window showing the contents of the selected - module.

 +

Opens a + View Module window, displaying the + contents of the selected module.
- The Process Menu + Process Menu

The following menu items apply to the currently selected - process, provided it is stopped at a breakpoint. See the chapter - about the Attach Process - window for more information.

+ process, provided it is stopped at a breakpoint (for details, see + section + Attach Process window):

Step Next Continue Finish +

The following menu items apply to the currently selected - process.

+ process:

Attach -

Attach to the process and open a - Attach Process window. -

- +

Attaches to the process and open an + Attach Process window.

 + Kill -

Terminate the process using exit(Pid,kill).

- +

Terminates the process using exit(Pid,kill).
-
- The Break Menu -

The items in this menu are used to create and delete - breakpoints. - See the Breakpoints - chapter for more information.

+
+ Break Menu +

The items in this menu are used to create and delete breakpoints. + For details, see section + Breakpoints.

+ Line Break... -

Set a line breakpoint.

 +

Sets a line breakpoint.

 Conditional Break... -

Set a conditional breakpoint.

 +

Sets a conditional breakpoint.

 Function Break... -

Set a function breakpoint.

 +

Sets a function breakpoint.

 Enable All -

Enable all breakpoints.

 +

Enables all breakpoints.

 Disable All -

Disable all breakpoints.

 +

Disables all breakpoints.

 - Delete All -

Remove all breakpoints.

 + Delete All +

Removes all breakpoints.

 -

For each breakpoint, a corresponding entry is added to - the Break - menu, from which it is possible to disable/enable or delete - the breakpoint, and to change its trigger action.

+

For each breakpoint, a corresponding entry is added to the + Break menu, from which it is possible to disable, enable, + or delete the breakpoint, and to change its trigger action.

- The Options Menu + Options Menu Trace Window -

Set which areas should be visible in - an Attach Process - window. Does not affect already existing - Attach Process windows.

+

Sets the areas to be visible in an + Attach Process window. + Does not affect existing Attach Process windows.

 Auto Attach -

Set at which events a debugged process should be - automatically attached to. Affects existing debugged - processes.

- - First Call - the first time a process calls a - function in an interpreted module. - On Exit - at process termination. - On Break - when a process reaches a - breakpoint. +

Sets the events a debugged process is to be attached + to automatically. Affects existing debugged processes.

+ +

First Call - The first time a process calls + a function in an interpreted module.

 +

On Exit - At process termination.

 +

On Break - When a process reaches a + breakpoint.

 Stack Trace -

Set stack trace option, see section +

Sets the stack trace option, see section Stack Trace. Does not - affect already existing debugged processes.

- - Stack On, Tail - save information about all - current calls. - Stack On, No Tail - save information about + affect existing debugged processes.

+ +

Stack On, Tail - Saves information about all + current calls.

 +

Stack On, No Tail - Saves information about current calls, discarding previous information when a tail - recursive call is made. - Stack Off - do not save any information about - current calls. + recursive call is made.

 +

Stack Off - Does not save any information about + current calls.

 Strings -

Set which integer lists should be printed as strings. - Does not affect already existing debugged processes.

- - - Use range of +pc flag - use the printable - character range set by the - - erl(1) flag +pc. - +

Sets the integer lists to be printed as strings. + Does not affect existing debugged processes.

+ +

Use range of +pc flag - Uses the printable + character range set by the erl(1) flag + +pc.

+ Back Trace Size... -

Set how many call frames should be fetched when - inspecting the call stack from the Attach Process window. - Does not affect already existing Attach Process windows.

+

Sets how many call frames to be fetched when + inspecting the call stack from the Attach Process window. + Does not affect existing Attach Process windows.
- The Windows Menu + Windows Menu

Contains a menu item for each open Debugger window. Selecting - one of the items will raise the corresponding window.

+ one of the items raises the corresponding window.

- The Help Menu + Help Menu Help -

View the Debugger documentation. Currently this - function requires a web browser to be up and running.

 +

Shows the Debugger documentation. This function requires a + web browser.
- +
- The Interpret Dialog Window + Interpret Modules Window -

The interpret dialog module is used for selecting which modules - to interpret. Initially, the window shows the modules (erl - files) and subdirectories of the current working directory.

+

The Interpret Modules window is used for selecting which modules + to interpret. Initially, the window displays the modules (erl + files) and subdirectories of the current working directory.

-

Interpretable modules are modules for which a BEAM file, compiled - with the option debug_info set, can be found in the same +

Interpretable modules are modules for which a .beam file, + compiled with option debug_info set, is located in the same directory as the source code, or in an ebin directory next to it.

-

Modules, for which the above requirements are not fulfilled, are - not interpretable and are therefore displayed within parentheses. -

+

Modules for which these requirements are not fulfilled are + not interpretable and are therefore displayed within parentheses.

-

The debug_info option causes debug information or - abstract code to be added to the BEAM file. This will - increase the size of the file, and also makes it possible to +

Option debug_info causes debug information or + abstract code to be added to the .beam file. + This increases the file size and makes it possible to reconstruct the source code. It is therefore recommended not to include debug information in code aimed for target systems.

An example of how to compile code with debug information using - erlc:
- % erlc +debug_info module.erl

- + erlc:

+ 
+% erlc +debug_info module.erl
+

An example of how to compile code with debug information from - the Erlang shell:
- 4> c(module, debug_info).

- + the Erlang shell:

+ 
+4> c(module, debug_info).
+ - The Interpret Dialog Window. + Interpret Modules Window -

Browse the file hierarchy and interpret the appropriate modules - by selecting a module name and pressing Choose (or - carriage return), or by double clicking the module name. - Interpreted modules have the type erl src. -

+

To browse the file hierarchy and interpret the appropriate modules, + either select a module name and click Choose (or + press carriage return), or double-click the module name. + Interpreted modules have the type erl src.

-

Pressing All will interpret all displayed modules in - the chosen directory.

+

To interpret all displayed modules in the chosen directory, click + All.

-

Pressing Done will close the window.

+

To close the window, click Done.

-

When the Debugger is started in global mode (which is - the default, see - debugger:start/0), - modules added (or deleted) for interpretation will be added (or - deleted) on all known Erlang nodes.

+

When Debugger is started in global mode (which is the default, see + debugger:start/0), + modules added (or deleted) for interpretation are added (or + deleted) on all known Erlang nodes.
- The Attach Process Window + Attach Process Window -

From an Attach Process window the user can interact with a +

From an Attach Process window, you can interact with a debugged process. One window is opened for each process that has - been attached to. Note that when attaching to a process, its - execution is automatically stopped. -

+ been attached to. Notice that when attaching to a process, its + execution is automatically stopped.

- The Attach Process Window. + Attach Process Window -

The window is divided into five parts:

- -

The Code area, showing the code being executed. The code - is indented and each line is prefixed with its line number. - If the process execution is stopped, the current line is - marked with -->. An existing break point at a line - is marked with a stop symbol. In the example above, - the execution has been stopped at line 6, before - the execution of fac/1.

-

Active breakpoints are shown in red, while inactive - breakpoints are shown in blue.

+

The window is divided into the following five parts:

+ +

The Code area, displaying the code being executed. The code + is indented and each line is prefixed with its line number. + If the process execution is stopped, the current line is + marked with -->. An existing break point at a line + is marked with a stop symbol. In the example shown in the + illustration, the execution stopped at line 6, before + the execution of fac/1.

+ +

Active breakpoints are displayed in red and inactive + breakpoints in blue.

 - The Button area, with buttons for quick access to frequently - used functions in the Process menu. - The Evaluator area, where the user can evaluate functions - within the context of the debugged process, provided that - process execution has been stopped. - The Bindings area, showing all variables bindings. - Clicking on a variable name will result in the value being - displayed in the Evaluator area. - Double-clicking on a variable name will open a window where - the variable value may be edited. Note however that pid, - reference, binary or port values can not be edited. + +

The Button area, with buttons for quick access to frequently + used functions in the Process menu.

 + +

The Evaluator area, where you can evaluate functions + within the context of the debugged process, if that + process execution is stopped.

 + +

The Bindings area, displaying all variables bindings. If you + click a variable name, the value is displayed in the Evaluator area. + Double-click a variable name to open a window where + the variable value can be edited. Notice however that pid, + reference, binary, or port values cannot be edited.

 -

The Trace area, showing a trace output for the process. -

+ +

The Trace area, which displays a trace output for the + process.

- ++ (N) <L> - Function call, where N is the call level and - L the line number. + ++ (N) <L> +

Function call, where N is the call level and + L the line number.

 - -- (N) - Function return value. + -- (N) +

Function return value

. - ==> Pid : Msg - The message Msg is sent to process Pid. - + ==> Pid : Msg +

The message Msg is sent to process + Pid.

 - - The message Msg is received. + +

The message Msg is received.

 - ++ (N) receive - Waiting in a receive. + ++ (N) receive +

Waiting in a receive.

 - ++ (N) receive with timeout - Waiting in a receive...after. - + ++ (N) receive with timeout +

Waiting in a receive...after.

 + -

Also the back trace, a summary of the current function calls - on the stack, is displayed in the Trace area.

+

The Trace area also displays Back Trace, a summary of the + current function calls on the stack.

 -

It is configurable using the Options menu which areas should - be shown or hidden. By default, all areas except the Trace area - are shown.

+

Using the Options menu, you can set which areas to be + displayed. By default, all areas except the Trace area are displayed.

- The File Menu + File Menu Close -

Close this window and detach from the process.

+

Closes this window and detach from the process.
- The Edit Menu + Edit Menu Go to line... -

Go to a specified line number.

 +

Goes to a specified line number.

 Search... -

Search for a specified string.

 +

Searches for a specified string.
- The Process Menu + Process Menu Step -

Execute the current line of code, stepping into any +

Executes the current code line, stepping into any (interpreted) function calls.

 Next -

Execute the current line of code and stop at the next +

Executes the current code line and stop at the next line.

 Continue -

Continue the execution.

 +

Continues the execution.

 Finish -

Continue the execution until the current function +

Continues the execution until the current function returns.

 Skip -

Skip the current line of code and stop at the next +

Skips the current code line and stop at the next line. If used on the last line in a function body, - the function will return skipped.

 + the function returns skipped.

Time Out -

Simulate a timeout when executing a +

Simulates a time-out when executing a receive...after statement.

 Stop -

Stop the execution of a running process, that is, make - the process stop as at a breakpoint. The command will take +

Stops the execution of a running process, that is, make + the process stop at a breakpoint. The command takes effect (visibly) the next time the process receives a message.

 Where -

Make sure the current location of the execution is +

Verifies that the current location of the execution is visible in the code area.

 Kill -

Terminate the process using exit(Pid,kill).

+

Terminates the process using exit(Pid,kill).

 Messages -

Inspect the message queue of the process. The queue is - printed in the evaluator area.

 +

Inspects the message queue of the process. The queue is + displayed in the Evaluator area.

 Back Trace -

Display the back trace of the process, a summary of - the current function calls on the stack, in the trace area. - Requires that the Trace area is visible and that the stack - trace option is 'Stack On, Tail' or 'Stack On, No Tail'.

+

Displays the back trace of the process, a summary of + the current function calls on the stack, in the Trace area. + Requires that the Trace area is visible and that the Stack + Trace option is Stack On, Tail or + Stack On, No Tail.

 Up -

Inspect the previous function call on the stack, +

Inspects the previous function call on the stack, showing the location and variable bindings.

 Down -

Inspect the next function call on the stack, showing +

Inspects the next function call on the stack, showing the location and variable bindings.
- The Options Menu + Options Menu Trace Window -

Set which areas should be visible. Does not affect - other Attach Process windows.

- +

Sets which areas are to be visible. Does not affect + other Attach Process windows.

 Stack Trace -

Same as in the Monitor - window, but only affects the debugged - process the window is attached to.

- +

Same as in the Monitor + window, but only affects the debugged + process the window is attached to.

 Strings -

Same as in the Monitor - window, but only affects the debugged - process the window is attached to.

- +

Same as in the Monitor + window, but only affects the debugged + process the window is attached to.

 Back Trace Size... -

Set how many call frames should be fetched when +

Sets how many call frames are to be fetched when inspecting the call stack. Does not affect other Attach - Process windows.

- + Process windows.
- Break, Windows and Help Menus + Break, Windows, and Help Menus -

The Break, Windows and Help menus look the same as in - the Monitor window, see the chapter - The Monitor Window, except - that the Breaks menu apply to the local breakpoints only.

+

The Break, Windows, and Help menus + are the same as in the + Monitor Window, except + that the Breaks menu applies only to local + breakpoints.

- The View Module Window + View Module Window -

The View Module window shows the contents of an interpreted +

The View Module window displays the contents of an interpreted module and makes it possible to set breakpoints.

- The View Module Window. + View Module Window

The source code is indented and each line is prefixed with its line number.

-

Clicking a line will highlight it and select it to be the target - of the breakpoint functions available from the Break menu. - Doubleclicking a line will set a line breakpoint on that line. - Doubleclicking a line with an existing breakpoint will remove - the breakpoint.

+

Clicking a line highlights it and selects it to be the target + of the breakpoint functions available from the Break menu. + To set a line breakpoint on a line, double-click it. + To remove the breakpoint, double-click the line with an existing + breakpoint.

Breakpoints are marked with a stop symbol.

File and Edit Menus -

The File and Edit menus look the same as in the Attach Process - window, see the chapter The Attach - Process Window.

+

The File and Edit menus are the same as in the + Attach Process Window.

- Break, Windows and Help Menus + Break, Windows, and Help Menus -

The Break, Windows and Help menus look the same as in - the Monitor window, see the chapter - The Monitor Window, except - that the Breaks menu apply to the local breakpoints only.

+

The Break, Windows, and Help menus + are the same as in the + Monitor Window, except + that the Break menu applies only to local breakpoints.

@@ -862,14 +852,14 @@ c_break(Bindings) -> Performance

Execution of interpreted code is naturally slower than for - regularly compiled modules. Using the Debugger also increases + regularly compiled modules. Using Debugger also increases the number of processes in the system, as for each debugged process another process (the meta process) is created.

-

It is also worth to keep in mind that programs with timers may +

It is also worth to keep in mind that programs with timers can behave differently when debugged. This is especially true when - stopping the execution of a process, for example at a - breakpoint. Timeouts can then occur in other processes that + stopping the execution of a process (for example, at a + breakpoint). Time-outs can then occur in other processes that continue execution as normal.

@@ -878,8 +868,8 @@ c_break(Bindings) ->

Code loading works almost as usual, except that interpreted modules are also stored in a database and debugged processes - uses only this stored code. Re-interpreting an interpreted - module will result in the new version being stored as well, but + use only this stored code. Reinterpreting an interpreted + module results in the new version being stored as well, but does not affect existing processes executing an older version of the code. This means that the code replacement mechanism of Erlang does not work for debugged processes.

@@ -888,22 +878,24 @@ c_break(Bindings) ->
Debugging Remote Nodes -

By using debugger:start/1, it can be specified if Debugger - should be started in local or global mode.

+

By using + debugger:start/1, + you can specify if Debugger is to be started in local or global + mode:

 debugger:start(local | global)
-

If no argument is provided, Debugger is started in global mode. -

+ +

If no argument is provided, Debugger starts in global mode.

In local mode, code is interpreted only at the current node. In global mode, code is interpreted at all known nodes. Processes - at other nodes executing interpreted code will automatically be - shown in the Monitor window and can be attached to like any other + at other nodes executing interpreted code are automatically + displayed in the Monitor window and can be attached to like any other debugged process.

-

It is possible, but definitely not recommended to start Debugger - in global mode on more than one node in a network, as they will - interfere with each other leading to inconsistent behaviour.

+

It is possible, but definitely not recommended, to start Debugger + in global mode on more than one node in a network, as the nodes + interfere with each other, leading to inconsistent behavior.

diff --git a/lib/debugger/doc/src/i.xml b/lib/debugger/doc/src/i.xml index 9ceba94b44..db89f23494 100644 --- a/lib/debugger/doc/src/i.xml +++ b/lib/debugger/doc/src/i.xml @@ -4,7 +4,7 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -29,35 +29,36 @@
i - Debugger/Interpreter Interface + Debugger/Interpreter Interface. -

The module i provides short forms for some of +

The i module provides short forms for some of the functions used by the graphical Debugger and some of - the functions in the int module, the Erlang interpreter. -

+ the functions in module + int, the Erlang interpreter.

This module also provides facilities for displaying status information about interpreted processes and break points.

It is possible to attach to interpreted processes by giving the corresponding process identity only. By default, an attachment - window pops up. Processes at other Erlang nodes can be + window is displayed. Processes at other Erlang nodes can be attached manually or automatically.

-

By preference, these functions can be included in the module - shell_default. By default, they are.

+

By preference, these functions can be included in module + stdlib:shell_default. + By default, they are included in that module.

 im() -> pid() - Start a graphical monitor + Start a graphical monitor.

Starts a new graphical monitor. This is the Monitor window, - the main window of the Debugger. All of the Debugger and + the main window of Debugger. All the Debugger and interpreter functionality is accessed from the Monitor window. - The Monitor window displays the status of all processes that - have been/are executing interpreted modules.

+ This window displays the status of all processes that + have been or are executing interpreted modules.

 @@ -66,7 +67,7 @@ ii(AbsModule) -> {module, Module} | error ini(AbsModules) -> ok ini(AbsModule) -> {module, Module} | error - Interpret a module + Interpret a module. AbsModules = [AbsModule] AbsModule = Module | File @@ -85,7 +86,7 @@ iq(AbsModule) -> ok inq(AbsModule) -> ok - Stop interpreting a module + Stop interpreting a module. AbsModule = Module | File  Module = atom() @@ -110,28 +111,27 @@ ip() -> ok - Make a printout of the current status of all interpreted - processes + Print the current status of all interpreted + processes. -

Makes a printout of the current status of all interpreted - processes.

+

Prints the current status of all interpreted processes.

 ic() -> ok Clear information about processes executing interpreted - code + code.

Clears information about processes executing interpreted code - byt removing all information about terminated processes.

+ by removing all information about terminated processes.

 iaa(Flags) -> true iaa(Flags, Function) -> true - Set when and how to attach to a process + Set when and how to attach to a process. Flags = [init | break | exit] Function = {Module,Name,Args} @@ -139,42 +139,41 @@  Args = [term()] -

Sets when and how to automatically attach to a debugged - process, see +

Sets when and how to attach to a debugged process + automatically, see int:auto_attach/2. Function defaults to the standard function used by - the Debugger.

+ Debugger.

 ist(Flag) -> true - Set how to save call frames + Set how to save call frames. Flag = all | no_tail | false

Sets how to save call frames in the stack, see - int:stack_trace/1. -

+ int:stack_trace/1.

 ia(Pid) -> ok | no_proc - Attach to a process + Attache to a process. Pid = pid() -

Attaches to the debugged process Pid. A Debugger +

Attaches to the debugged process Pid. An Attach Process window is opened for the process.

 ia(X,Y,Z) -> ok | no_proc - Attach to a process + Attache to a process. X = Y = Z = int() @@ -186,7 +185,7 @@ ia(Pid, Function) -> ok | no_proc - Attach to a process + Attache to a process. Pid = pid() Function = {Module,Name} @@ -194,14 +193,14 @@

Attaches to the debugged process Pid. The interpreter - will call spawn(Module, Name, [Pid]) (and ignore + calls spawn(Module, Name, [Pid]) (and ignores the result).

 ia(X,Y,Z, Function) -> ok | no_proc - Attach to a process + Attache to a process. X = Y = Z = int() Function = {Module,Name} @@ -211,15 +210,15 @@

Same as ia(Pid, Function), where Pid is the result of calling the shell function pid(X,Y,Z). An attached process is expected to call the unofficial - int:attached(Pid) function and to be able to handle - messages from the interpreter, see dbg_wx_trace.erl for - an example.

+ function int:attached(Pid) and to be able to handle + messages from the interpreter. For an example, see + dbg_wx_trace.erl.

 ib(Module, Line) -> ok | {error, break_exists} - Create a breakpoint + Create a breakpoint. Module = atom() Line = int() @@ -232,20 +231,20 @@ ib(Module, Name, Arity) -> ok | {error, function_not_found} - Create breakpoints in the specified function + Create breakpoints in the specified function. Module = Name = atom() Arity = int()

Creates breakpoints at the first line of every clause of - the Module:Name/Arity function.

+ function Module:Name/Arity.

 ir() -> ok - Delete all breakpoints + Delete all breakpoints.

Deletes all breakpoints.

 @@ -253,7 +252,7 @@ ir(Module) -> ok - Delete all breakpoints in a module + Delete all breakpoints in a module. Module = atom() @@ -264,61 +263,57 @@ ir(Module, Line) -> ok - Delete a breakpoint + Delete a breakpoint. Module = atom() Line = int() -

Deletes the breakpoint located at Line in - Module.

+

Deletes the breakpoint at Line in Module.

 ir(Module, Name, Arity) -> ok | {error, function_not_found} - Delete breakpoints from the specified function - + Delete breakpoints from the specified function. Module = Name = atom() Arity = int()

Deletes the breakpoints at the first line of every clause of - the Module:Name/Arity function.

+ function Module:Name/Arity.

 ibd(Module, Line) -> ok - Make a breakpoint inactive + Make a breakpoint inactive. Module = atom() Line = int() -

Makes the breakpoint at Line in Module - inactive.

+

Makes the breakpoint at Line in Module inactive.

 ibe(Module, Line) -> ok - Make a breakpoint active + Make a breakpoint active. Module = atom() Line = int() -

Makes the breakpoint at Line in Module active. -

+

Makes the breakpoint at Line in Module active.

 iba(Module, Line, Action) -> ok - Set the trigger action of a breakpoint + Set the trigger action of a breakpoint. Module = atom() Line = int() @@ -332,7 +327,7 @@ ibc(Module, Line, Function) -> ok - Set the conditional test of a breakpoint + Set the conditional test of a breakpoint. Module = atom() Line = int() @@ -346,62 +341,53 @@

The conditional test is performed by calling Module:Name(Bindings), where Bindings is the current variable bindings. The function must return - true (break) or false (do not break). Use - int:get_binding(Var, Bindings) to retrieve the value - of a variable Var.

+ true (break) or false (do not break). + To retrieve the value of a variable Var, use + int:get_binding(Var, Bindings).

 ipb() -> ok - Make a printout of all existing breakpoints + Print all existing breakpoints. -

Makes a printout of all existing breakpoints.

+

Prints all existing breakpoints.

 ipb(Module) -> ok - Make a printout of all breakpoints in a module - + Print all existing breakpoints in a module. Module = atom() -

Makes a printout of all existing breakpoints in - Module.

+

Prints all existing breakpoints in Module.

 iv() -> atom() - Current version number of the interpreter + Return the current version number of the interpreter. +

Returns the current version number of the interpreter. - The same as the version number of the Debugger application. -

+ Same as the version number of the Debugger application.

 help() -> ok - Print help text + Print help text.

Prints help text.

 -
- Usage - -

Refer to the Debugger User's Guide for information about - the Debugger.

-
-
See Also -

int(3)

+

int(3)

 diff --git a/lib/debugger/doc/src/int.xml b/lib/debugger/doc/src/int.xml index ea21d04a07..31e9dfe923 100644 --- a/lib/debugger/doc/src/int.xml +++ b/lib/debugger/doc/src/int.xml @@ -4,7 +4,7 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -29,16 +29,16 @@
int - Interpreter Interface + Interpreter Interface.

The Erlang interpreter provides mechanisms for breakpoints and - stepwise execution of code. It is mainly intended to be used by - the Debugger, see Debugger User's Guide and - debugger(3).

+ stepwise execution of code. It is primarily intended to be used by + Debugger, see the User's Guide and + debugger(3).

-

From the shell, it is possible to:

- - Specify which modules should be interpreted. +

The following can be done from the shell:

+ + Specify the modules to be interpreted. Specify breakpoints. Monitor the current status of all processes executing code in interpreted modules, also processes at other Erlang nodes. @@ -48,45 +48,48 @@

By attaching to a process executing interpreted code, it is possible to examine variable bindings and order stepwise execution. This is done by sending and receiving information - to/from the process via a third process, called the meta process. - It is possible to implement your own attached process. See + to/from the process through a third process, called the meta + process. You can implement your own attached process. See int.erl for available functions and dbg_wx_trace.erl for possible messages.

-

The interpreter depends on the Kernel, STDLIB and GS - applications, which means modules belonging to any of these - applications are not allowed to be interpreted as it could lead +

The interpreter depends on the Kernel, STDLIB, and + GS applications. This means that modules belonging to any of + these applications are not allowed to be interpreted, as it could lead to a deadlock or emulator crash. This also applies to modules - belonging to the Debugger application itself.

+ belonging to the Debugger application.
+ Breakpoints

Breakpoints are specified on a line basis. When a process executing code in an interpreted module reaches a breakpoint, it - will stop. This means that that a breakpoint must be set at an - executable line, that is, a line of code containing an executable + stops. This means that a breakpoint must be set at an + executable line, that is, a code line containing an executable expression.

-

A breakpoint have a status, a trigger action and may have a - condition associated with it. The status is either active - or inactive. An inactive breakpoint is ignored. When a - breakpoint is reached, the trigger action specifies if - the breakpoint should continue to be active (enable), if - it should become inactive (disable), or if it should be - removed (delete). A condition is a tuple - {Module,Name}. When the breakpoint is reached, - Module:Name(Bindings) is called. If this evaluates to - true, execution will stop. If this evaluates to - false, the breakpoint is ignored. Bindings contains - the current variable bindings, use get_binding to retrieve - the value for a given variable.

+

A breakpoint has the following:

+ + A status, which is active or inactive. An + inactive breakpoint is ignored. + A trigger action. When a breakpoint is reached, the trigger + action specifies if the breakpoint is to continue as active + (enable), or to become inactive (disable), or + to be removed (delete). + Optionally an associated condition. A condition is a tuple + {Module,Name}. When the breakpoint is reached, + Module:Name(Bindings) is called. If it evaluates to + true, execution stops. If it evaluates to false, + the breakpoint is ignored. Bindings contains the current + variable bindings. To retrieve the value for a specified variable, + use get_binding. +

By default, a breakpoint is active, has trigger action - enable and has no condition associated with it. For more - detailed information about breakpoints, refer to Debugger User's - Guide.

+ enable, and has no associated condition. For details + about breakpoints, see the User's Guide.

@@ -95,7 +98,7 @@ i(AbsModules) -> ok ni(AbsModule) -> {module,Module} | error ni(AbsModules) -> ok - Interpret a module + Interpret a module. AbsModules = [AbsModule] AbsModule = Module | File | [Module | File] @@ -107,41 +110,43 @@ the module only at the current node. ni/1 interprets the module at all known nodes.

-

A module may be given by its module name (atom) or by its - file name. If given by its module name, the object code +

A module can be specified by its module name (atom) or + filename.

+ +

If specified by its module name, the object code Module.beam is searched for in the current path. The source code Module.erl is searched for first in - the same directory as the object code, then in a src + the same directory as the object code, then in an src directory next to it.

-

If given by its file name, the file name may include a path - and the .erl extension may be omitted. The object code +

If specified by its filename, the filename can include a path + and the .erl extension can be omitted. The object code Module.beam is searched for first in the same directory as the source code, then in an ebin directory next to it, and then in the current path.

-

The interpreter needs both the source code and the object - code, and the object code must include debug - information. That is, only modules compiled with the option +

The interpreter requires both the source code and the object + code. The object code must include debug + information, that is, only modules compiled with option debug_info set can be interpreted.

The functions returns {module,Module} if the module - was interpreted, or error if it was not.

+ was interpreted, otherwise error is returned.

-

The argument may also be a list of modules/file names, in +

The argument can also be a list of modules or filenames, in which case the function tries to interpret each module as - specified above. The function then always returns ok, - but prints some information to stdout if a module could not be - interpreted.

+ specified earlier. The function then always returns ok, + but prints some information to stdout if a module + cannot be interpreted.

n(AbsModule) -> ok nn(AbsModule) -> ok - Stop interpreting a module + Stop interpreting a module. AbsModule = Module | File | [Module | File]  Module = atom() @@ -152,14 +157,14 @@ interpreting the module only at the current node. nn/1 stops interpreting the module at all known nodes.

-

As for i/1 and ni/1, a module may be given by - either its module name or its file name.

+

As for i/1 and ni/1, a module can be specified by + its module name or filename.

 interpreted() -> [Module] - Get all interpreted modules + Get all interpreted modules. Module = atom() @@ -170,20 +175,20 @@ file(Module) -> File | {error,not_loaded} - Get the file name for an interpreted module + Get the filename for an interpreted module. Module = atom() File = string() -

Returns the source code file name File for an +

Returns the source code filename File for an interpreted module Module.

 interpretable(AbsModule) -> true | {error,Reason} - Check if a module is possible to interpret + Check if a module can be interpreted. AbsModule = Module | File  Module = atom() @@ -193,45 +198,59 @@  App = atom() -

Checks if a module is possible to interpret. The module can - be given by its module name Module or its source file - name File. If given by a module name, the module is - searched for in the code path.

- -

The function returns true if both source code and - object code for the module is found, the module has been - compiled with the option debug_info set and does not - belong to any of the applications Kernel, STDLIB, GS or - Debugger itself.

- -

The function returns {error,Reason} if the module for - some reason is not possible to interpret.

- -

Reason is no_src if no source code is found or - no_beam if no object code is found. It is assumed that - the source- and object code are located either in the same - directory, or in src and ebin directories next - to each other.

- -

Reason is no_debug_info if the module has not - been compiled with the option debug_info set.

- -

Reason is badarg if AbsModule is not - found. This could be because the specified file does not - exist, or because code:which/1 does not return a - beam file name, which is the case not only for non-existing - modules but also for modules which are preloaded or cover - compiled.

- -

Reason is {app,App} where App is - kernel, stdlib, gs or debugger if - AbsModule belongs to one of these applications.

- -

Note that the function can return true for a module - which in fact is not interpretable in the case where +

Checks if a module can be interpreted. The module can be + specified by its module name Module or its source + filename File. If specified by a module name, the module + is searched for in the code path.

+ +

The function returns true if all of the following + apply:

+ + Both source code and object code for the module is + found. + The module has been compiled with option debug_info + set. + The module does not belong to any of the applications + Kernel, STDLIB, GS, or Debugger. + + +

The function returns {error,Reason} if the module cannot + be interpreted. Reason can have the following values:

+ + no_src +

No source code is found. + It is assumed that the source code and object code are located + either in the same directory, or in src and ebin + directories next to each other.

 + + no_beam +

No object code is found. + It is assumed that the source code and object code are located + either in the same directory, or in src and ebin + directories next to each other.

 + + no_debug_info +

The module has not been compiled with option + debug_info set.

 + + badarg +

AbsModule is not found. This could be because + the specified file does not exist, or because + code:which/1 does not return a BEAM filename, + which is the case not only for non-existing modules but also + for modules that are preloaded or cover-compiled.

 + + {app,App} +

App is kernel, stdlib, gs, + or debugger if AbsModule belongs to one of these + applications.

 + + +

Notice that the function can return true for a module + that in fact is not interpretable in the case where the module is marked as sticky or resides in a directory - marked as sticky, as this is not discovered until - the interpreter actually tries to load the module.

+ marked as sticky. The reason is that this is not discovered + until the interpreter tries to load the module.

 @@ -239,7 +258,7 @@ auto_attach() -> false | {Flags,Function} auto_attach(false) auto_attach(Flags, Function) - Get/set when and how to attach to a process + Get and set when and how to attach to a process. Flags = [init | break | exit] Function = {Module,Name,Args} @@ -247,24 +266,24 @@  Args = [term()] -

Gets and sets when and how to automatically attach to a +

Gets and sets when and how to attach automatically to a process executing code in interpreted modules. false - means never automatically attach, this is the default. + means never attach automatically, this is the default. Otherwise automatic attach is defined by a list of flags and - a function. The following flags may be specified:

- - init - attach when a process for the very first + a function. The following flags can be specified:

+ + init - Attach when a process for the first time calls an interpreted function. - break - attach whenever a process reaches a + break - Attach whenever a process reaches a breakpoint. - exit - attach when a process terminates. + exit - Attach when a process terminates.

When the specified event occurs, the function Function - will be called as:

+ is called as:

-spawn(Module, Name, [Pid | Args])
-
+spawn(Module, Name, [Pid | Args]) +

Pid is the pid of the process executing interpreted code.

 @@ -273,7 +292,7 @@ spawn(Module, Name, [Pid | Args]) stack_trace() -> Flag stack_trace(Flag) - Get/set if and how to save call frames + Get and set if and how to save call frames. Flag = all | no_tail | false @@ -281,25 +300,30 @@ spawn(Module, Name, [Pid | Args])

Gets and sets how to save call frames in the stack. Saving call frames makes it possible to inspect the call chain of a process, and is also used to emulate the stack trace if an - error (an exception of class error) occurs.

- - all - save information about all current calls, - that is, function calls that have not yet returned a value. - - no_tail - save information about current calls, + error (an exception of class error) occurs. The following + flags can be specified:

+ + all +

Save information about all current calls, + that is, function calls that have not yet returned a value.

+ + + no_tail +

Save information about current calls, but discard previous information when a tail recursive call - is made. This option consumes less memory and may be + is made. This option consumes less memory and can be necessary to use for processes with long lifetimes and many - tail recursive calls. This is the default. - false - do not save any information about current - calls. - + tail recursive calls. This is the default.

 + + false +

Save no information about currentcalls.

 + break(Module, Line) -> ok | {error,break_exists} - Create a breakpoint + Create a breakpoint. Module = atom() Line = int() @@ -311,86 +335,80 @@ spawn(Module, Name, [Pid | Args]) delete_break(Module, Line) -> ok - Delete a breakpoint + Delete a breakpoint. Module = atom() Line = int() -

Deletes the breakpoint located at Line in - Module.

+

Deletes the breakpoint at Line in Module.

 break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Create breakpoints in the specified function + Create breakpoints in the specified function. Module = Name = atom() Arity = int()

Creates a breakpoint at the first line of every clause of - the Module:Name/Arity function.

+ function Module:Name/Arity.

 del_break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Delete breakpoints from the specified function - + Delete breakpoints from the specified function. Module = Name = atom() Arity = int()

Deletes the breakpoints at the first line of every clause of - the Module:Name/Arity function. -

+ function Module:Name/Arity.

 no_break() -> ok no_break(Module) -> ok - Delete all breakpoints + Delete all breakpoints. -

Deletes all breakpoints, or all breakpoints in Module. -

+

Deletes all breakpoints, or all breakpoints in Module.

 disable_break(Module, Line) -> ok - Make a breakpoint inactive + Make a breakpoint inactive. Module = atom() Line = int() -

Makes the breakpoint at Line in Module - inactive.

+

Makes the breakpoint at Line in Module inactive.

 enable_break(Module, Line) -> ok - Make a breakpoint active + Make a breakpoint active. Module = atom() Line = int() -

Makes the breakpoint at Line in Module active. -

+

Makes the breakpoint at Line in Module active.

 action_at_break(Module, Line, Action) -> ok - Set the trigger action of a breakpoint + Set the trigger action of a breakpoint. Module = atom() Line = int() @@ -404,7 +422,7 @@ spawn(Module, Name, [Pid | Args]) test_at_break(Module, Line, Function) -> ok - Set the conditional test of a breakpoint + Set the conditional test of a breakpoint. Module = atom() Line = int() @@ -414,14 +432,14 @@ spawn(Module, Name, [Pid | Args])

Sets the conditional test of the breakpoint at Line in Module to Function. The function must - fulfill the requirements specified in the section - Breakpoints above.

+ fulfill the requirements specified in section + Breakpoints.

 get_binding(Var, Bindings) -> {value,Value} | unbound - Retrieve a variable binding + Retrieve a variable binding. Var = atom() Bindings = term() @@ -437,7 +455,7 @@ spawn(Module, Name, [Pid | Args]) all_breaks() -> [Break] all_breaks(Module) -> [Break] - Get all breakpoints + Get all breakpoints. Break = {Point,Options}  Point = {Module,Line} @@ -451,15 +469,14 @@ spawn(Module, Name, [Pid | Args])     Name = atom() -

Gets all breakpoints, or all breakpoints in Module. -

+

Gets all breakpoints, or all breakpoints in Module.

 snapshot() -> [Snapshot] Get information about all processes executing interpreted - code + code. Snapshot = {Pid, Function, Status, Info}  Pid = pid() @@ -475,26 +492,27 @@ spawn(Module, Name, [Pid | Args])

Gets information about all processes executing interpreted code.

- - Pid - process identifier. - Function - first interpreted function called by + + Pid - Process identifier. + Function - First interpreted function called by the process. - Status - current status of the process. - Info - additional information. + Status - Current status of the process. + Info - More information. -

Status is one of:

- - idle - the process is no longer executing + +

Status is one of the following:

+ + idle - The process is no longer executing interpreted code. Info={}. - running - the process is running. Info={}. + running - The process is running. Info={}. - waiting - the process is waiting at a + waiting - The process is waiting at a receive. Info={}. - break - process execution has been stopped, + break - Process execution is stopped, normally at a breakpoint. Info={Module,Line}. - exit - the process has terminated. + exit - The process is terminated. Info=ExitReason. - no_conn - the connection is down to the node + no_conn - The connection is down to the node where the process is running. Info={}. @@ -503,7 +521,7 @@ spawn(Module, Name, [Pid | Args]) clear() -> ok Clear information about processes executing interpreted - code + code.

Clears information about processes executing interpreted code by removing all information about terminated processes.

@@ -513,13 +531,13 @@ spawn(Module, Name, [Pid | Args]) continue(Pid) -> ok | {error,not_interpreted} continue(X,Y,Z) -> ok | {error,not_interpreted} - Resume process execution + Resume process execution. Pid = pid() X = Y = Z = int() -

Resume process execution for Pid, or for +

Resumes process execution for Pid or c:pid(X,Y,Z).

 diff --git a/lib/debugger/doc/src/introduction.xml b/lib/debugger/doc/src/introduction.xml new file mode 100644 index 0000000000..9f5f279bb0 --- /dev/null +++ b/lib/debugger/doc/src/introduction.xml @@ -0,0 +1,63 @@ + + + + +
+ + 19972013 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Introduction + + + + + introduction.xml +
+ +
+ Scope +

Debugger is a graphical user interface for the Erlang + interpreter, which can be used for debugging and testing of + Erlang programs. For example, breakpoints can be set, code can be + single-stepped and variable values can be displayed and changed. +

+ +

The Erlang interpreter can also be accessed through the interface + module int(3). +

+ + +

Debugger might at some point + start tracing on the processes that execute the interpreted + code. This means that a conflict occurs if tracing by other + means is started on any of these processes.

+ +
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language.

+

Modules to be debugged must include debug information, + for example, erlc +debug_info MODULE.erl.

+
+ + + + diff --git a/lib/debugger/doc/src/part.xml b/lib/debugger/doc/src/part.xml index 7515c0ad5b..ce1edbd978 100644 --- a/lib/debugger/doc/src/part.xml +++ b/lib/debugger/doc/src/part.xml @@ -4,7 +4,7 @@
- 19972013 + 19972016 Ericsson AB. All Rights Reserved. @@ -27,14 +27,10 @@ 1998-05-12 B - part.sgml + part.xml
- -

Debugger is a graphical tool which can be used for - debugging and testing of Erlang programs. For example, breakpoints - can be set, code can be single stepped and variable values can be - displayed and changed.

- + + diff --git a/lib/debugger/doc/src/ref_man.xml b/lib/debugger/doc/src/ref_man.xml index 6df9e90c2c..c44f07f912 100644 --- a/lib/debugger/doc/src/ref_man.xml +++ b/lib/debugger/doc/src/ref_man.xml @@ -28,12 +28,7 @@
- -

Debugger is a graphical tool which can be used for - debugging and testing of Erlang programs. For example, breakpoints - can be set, code can be single stepped and variable values can be - displayed and changed.

- + -- cgit v1.2.3