RCUG RootCause GUI Reference

From OC Systems Wiki!
Jump to: navigation, search


Next Previous Index Top

RootCause User Guide


Contents

RootCause GUI Reference

This chapter describes all parts of the Rootcause Console Graphical User Interface, or the "RootCause GUI" for short. It is meant to serve as a reference to supplement the text provided by the Help buttons on the windows themselves.

Workspace Browser

The Workspace Browser is the main window of the RootCause GUI. The Workspace Browser controls the program tracing process.

The Workspace Browser is composed of the following parts:

Workspace Tree

The Workspace Tree displays information about the current workspace. There are three sections to this tree: Program node, UALs node, and Data node. A Workspace Tree Popup Menu is provided to perform operations on nodes in the Workspace Tree.

Workspace Tree Popup Menu

Select a node in the Workspace Tree and use the right mouse button (MB3) to display a popup menu. The following operations from the Workspace and Setup menus are provided, depending on the node selected:

Program node

The program configuration is displayed under the Program node. This includes the main program and any dynamic modules used by the program as specified by the user using Add Dynamic Module in the Workspace Menu.

UALs node

The configuration of user action libraries (UALs) is displayed under the UALs node. The trace predefined UAL is always present, and other predefined UALs are displayed depending upon the local configuration. Each can be selected by checking the box to the left of the UAL name, and disabled by clearing the checkbox.

NOTE: a Build operation is required to apply the changes made to the UALs tree.

The predefined UALs are program-wide actions that can be optionally applied by clicking the checkbox next to the name. Additional predefined UALs may be written and added with Setup->Add UAL, or by directly editing the file $APROBE/ual_lib/predefined_uals.

log_env

Use the log_env predefined UAL to collect information about the environment in which the program is running. This information includes environment variables, the current user and machine, and other information. This information will appear in the Program Information Pane of the Trace Display window.

exceptions

Enable the exceptions predefined UAL to trace C++ (and Ada) exceptions that occur in the program. These will show up as exception events in the Trace Index Dialog, and a full traceback will appear in the Event Details Pane of the Trace Display window.

java_exceptions

Enable the java_exceptions predefined UAL to trace Java exceptions that occur in the program.

verify

Enable the verify predefined UAL to verify the traced modules are the same between run-time and format-time. This introduces some startup overhead, but is recommended when deploying a workspace for use in a different environment. See "Deploying A RootCause Workspace".

sigsegv

The sigsegv predefined UAL, enabled by default, logs a traceback when one of several program-termination signals occurs: SIGQUIT, SIGILL, SIGABRT, SIGBUS, SIGSEGV, or SIGTERM. The traceback will appear int he Event Details Pane of the Trace Display window.

Data node

The most recent Process Data Sets are shown under the Data node in the Workspace Tree, most-recent-first. Double-clicking on a PROCESS DATA node will open and update the Trace Index Dialog for that data.

Data is recorded when the program registered with the current workspace is run with rootcause on. The data is organized per-process into a Process Data Set, and is identified by the process id. By default, only the two most recent data sets are kept; older ones are deleted. More data may be preserved by increasing the value labeled "Keep logged data for N previous processes" in the RootCause Options Tab tab of Options Dialog opened from the Setup Menu.

Message Pane

The Message Pane displays information about the operations performed on the workspace. A popup menu is accessible (via the right mouse button) in the message pane, and provides access to the operations in the Edit Menu.

Workspace Menu

The Workspace Menu is the leftmost menu in the Workspace Browser window and contains many fundamental operations.

New

You must have a workspace to begin work tracing a program. A single program is associated with each workspace. You can create a new workspace using New. First the current workspace will be saved, if it has been changed but not yet saved. The New Workspace Dialog allows you to set the name and location of the workspace and set the program associated with the workspace.

Open

The user can work with an existing workspace by choosing Open. First the current workspace will be saved, if it has been changed but not yet saved. Then the user can choose an existing workspace and it will be loaded and the user can resume from where the workspace was last saved.

Save

The current workspace can be saved, if it has been modified, by choosing Save. All information about the program configuration and traces will be saved.

Save As

The current workspace can be renamed by choosing Save As. The user will choose the new name of the workspace, and it will be saved to the workspace file. The new workspace must be rebuilt using the Build operation before it can be accessed by a running program. If a workspace file with the chosen name already exists, the user will be asked if the file should be overwritten. The user can cancel the operation or proceed to overwrite the existing workspace file.

Close

Choose Close to close the workspace without exiting RootCause. You will be asked if you want to save the workspace, if it is needed.

Recent Workspaces

The most recently visited workspaces can be opened by choosing them from the Recent Workspaces submenu. The chosen workspace will be loaded and work can resume from where the workspace was last saved.

Open RootCause Log

The RootCause Log can be examined by choosing Open RootCause Log. The RootCause log records which programs have been started and which have been traced since RootCause was enabled. This can be a good starting point for determining which programs should be traced in a large, multi-program application suite.

Decollect Collected

Choose Decollect Collected to unpack the data collected on a remote computer (after a deploy operation). The decollected data will consist of one or more workspaces of data. This will open the Decollect Data Dialog to choose the source (.clct) file and destination (.dclct) directory. Upon successful completion, a Trace Index Dialog is opened to index the newest data within the decollection.

Open Decollection

Decollected workspaces, which have been collected from a remote computer, can be examined using Open Decollection. The user will choose a decollection, which was produced by a previous Decollect Collected operation, and a Trace Index Dialog will be opened.

Recent Decollections

The most recently visited decollections can be opened by choosing them from the Recent Decollections submenu. A Trace Index Dialog is opened to index the newest data within the decollection.

List RootCause Registry

The RootCause registry defines what workspaces apply to which applications. You can list the current contents of the RootCause registry with List RootCause Registry.

Register Program

The current workspace can be registered with its corresponding program or class using Register Program.

Unregister Program

You can remove the RootCause registry entry for the current workspace/program with Unregister Program.

Reset Program

You can reset the program associated with a workspace if it has been rebuilt, or its location has changed. Choose Reset Program to select the new version of the program. When the program is reset, the existing trace setup will be checked against the new version, and any invalid traces will be discarded. Traces are invalid if the function/data no longer exists in the program.

Add Dynamic Module

Any number of runtime-loaded dynamic modules (shared libraries) can be added to the program configuration by choosing Add Dynamic Module. The user will then select the dynamic module through a file chooser dialog. If this module is not already part of the program configuration it will be added to the program configuration and displayed in the workspace tree.

Reset Dynamic Module

You can reset a dynamic module associated with a workspace if it has been rebuilt, or its location has changed. Select a dynamic module in the workspace tree then choose Reset Dynamic Module to select the new version of the module. When a module is reset, the existing trace setup will be checked against the new version, and any invalid traces will be discarded. Traces are invalid if the function/data no longer exists in the module.

Delete Dynamic Module

You can remove a dynamic module associated with a workspace by selecting a dynamic module in the workspace tree and choosing Delete Dynamic Module. When a module is deleted any traces within the module will be lost.

Update J2EE Modules

You can add or change the J2EE modules associated with a workspace with Update J2EE Modules. This pops up a File Chooser dialog with which you enter the directory where deployable Enterprise Java Bean (EJB) and Servlet classes and jars reside. If you've already specified a path, this will cause that to be re-read and the list of Java modules updated. See "RootCause Shipped as Part of Your Application" for more information.

Exit

Choose Exit to terminate the RootCause GUI. You will be asked if you want to save the workspace, if it is needed.

Edit Menu

The Edit Menu supports Copy/Cut/Paste/Delete from the Message pane. If you are using RootCause on a version of Solaris less than 8, the Copy operation here is the only way to copy text from the Message window. If you are using Solaris 8, the normal mouse copy/paste operations work directly. These operations are also available on a popup (context) menu by right-clicking within the Messages window.

Cut

Choose Cut to cut the selected text from the message pane and copy it to the system clipboard.

Copy

Choose Copy to copy the selected text from the message pane to the system clipboard.

Paste

Choose Paste to paste text from the system clipboard into the message pane at the current cursor position.

Delete

Choose Delete to delete the selected text from the message pane.

Setup Menu

Once you have chosen a workspace and defined the program configuration, you can use the items in the Setup Menu to set up options.

Trace UAL

Choose Trace UAL to set up options to control the predefined trace UAL. This is the primary means for tracing program execution. This will open the Trace Setup Dialog.

Add UAL

Choose Add UAL to add a new UAL to the workspace. This allows you to add your own "predefined" UALs to a workspace and control their configuration. This will open the Add UAL Dialog.

Edit UAL

Choose Edit UAL to edit parameters or other configuration associated with the selected UAL. (This is insensitive unless a UAL is selected.) This will open the UAL-specific configuration dialog, such as the Trace Setup Dialog; or else the default dialog which simply allows UAL parameters to be specified when the UAL is used by aprobe and apformat. Note that the "-p" argument that is used to indicate parameters for a UAL should not be specified here.

Remove UAL

Choose Remove UAL to remove a UAL from the list displayed under the UALs node. This item is insensitive if no UAL is selected, or if the selected UAL is predefined.

Build

Choose Build to compile the trace setup into a UAL in preparation for running the program locally or deploying the trace to a remote computer.

Options

Choose Options to open the RootCause Options Dialog, from which most workspace configuration items are selected.

Source Path

Choose Source Path to set up the search path used to find source files in the Trace Setup and Trace Display windows. Source files will be displayed when you define a trace, and also when you view logged trace events. This will open the Edit Source Path Dialog.

Execute Menu

Once you have set up the traces you want for your program you can use items in the Execute Menu to define other aprobe options, and run the program with the traces.

Run Program

Choose Run Program to run the program on the local computer (the same computer running the RootCause GUI) with the defined traces. This option is useful when developing traces on the local computer. Registered programs can be run outside of RootCause from the command-line or from a script or batch file, but this may be more convenient. This will open the Run Program Dialog.

Deploy Program

Choose Deploy Program to deploy the current set of traces to a remote computer where the RootCause Agent is installed. The traces and options selected in the current workspace will be packaged up to be sent to the remote computer. This will open the Deploy Dialog.

Analyze Menu

Once you have run your program with the traces you specified, you can analyze the logged data.

Index Process Data

Choose Index Process Data to build an index for the most recently logged data in the workspace. This will open the Trace Index Dialog.

Examine Process Data

Choose Examine Process Data to examine the most recently logged data in the workspace. This will open the Trace Data Dialog.

Help Menu

Use the Help Menu to figure out what is going on and how to get things done.

Toolbar

Use the Toolbar to access common menu items quickly.

Setup

Choose Setup to set up traces. This will open the Trace Setup Dialog.

Build

Choose Build to compile the trace setup in preparation for running the program locally or deploying the traces to a remote computer.

Run

Choose Run to run the program locally. This will open the Run Program Dialog. Registered programs can be run outside of RootCause from the command-line or from a script or batch file, but this may be more convenient.

Deploy

Choose Deploy to deploy the traces to a remote computer. This will open the Deploy Dialog.

Decollect

Choose Decollect to unpack data collected from a remote computer. This will open the Decollect Data Dialog.

Index

Choose Index to build an index for the most recently logged data in the workspace. This will open the Trace Index Dialog.

Examine

Choose Examine to examine the most recently logged data in the workspace. This will open the Trace Data Dialog.

Reset Program Dialog

The Reset Program Dialog permits the user to reset the program associated with a workspace when the program is rebuilt or moved to a new location. The workspace will reconcile the changes to the program with the trace setup selected, discard any invalid trace options, and define the program which will be traced. A single program is associated with each workspace.

Program File

The program name can be entered in the text field labeled Program File or can be selected using the "..." button to the right of the text field. The program must exist and must have execute permission. The field will be initialized with the current program.

Buttons

Once a valid program file has been selected click the OK button to reset the program. Use the Cancel button to dismiss the dialog without resetting the program. Use the Help button to figure out what is going on and how to get things done.

Add UAL Dialog

The Add Ual Dialog configures a user-defined UAL and adds it to the workspace. Select Add UAL from the Setup Menu menu to open this dialog. Once a UAL is added to the workspace it can be enabled and disabled via the checkbox, and other options can be specified by double-clicking on it to open the UAL Options Dialog.

Note: This is an advanced feature, and users are encouraged to contact OC Systems for support.

Plug-In Class

If the UAL to be added requires a separate interface for configuration and operation within RootCause, that Java class name should be specified in the text field labeled Plug-in Class. Most UALs will not require a special interface and this field can be left blank.

UAL File

Specify the file (path) containing the UAL in the text field labeled UAL File. This identifies the actual UAL to be added to the workspace.

Name of UAL

Specify the name to use to display the UAL in the workspace tree in the text field labeled Name of UAL. Normally this will match the UAL file name.

UAL Description

Specify a brief description of the UAL in the text field labeled UAL Description. This will also be displayed in the workspace tree. This description may highlight any special configuration of the UAL.

Copy UAL

Check the box labeled Copy UAL to copy the UAL to the workspace. This is the recommended method of ensuring the UAL is available on a remote computer if the workspace is deployed.

Requires Trace UAL

Check the box labeled Requires Trace UAL if the new UAL requires that the Trace UAL be active when it is active.

Aprobe Parameters

Specify the string to follow the "-p" option after the UAL File on the aprobe command-line. Do not include the "-p" itself. For example, to specify a configuration file in the workspace, you might enter:

-c $RC_WORKSPACE_LOC/events.cfg

Apformat Parameters

Specify the string to follow the "-p" option after the UAL File on the apformat command-line. Do not include the "-p" itself. You can refer to files in the workspace itself with the RC_WORKSPACE_LOC environment variables.

Buttons

Use the OK button to add the new UAL as specified. Use the Cancel button to abandon the operation. Use the Help button to figure out what is going on and how to get things done.

RootCause Options Dialog

The Options item in the Setup Menu opens the RootCause Options Dialog, from which most options for building, running, formatting and displaying your traces are specified. It consists of a number of tabs, but the RootCause Options Tab, shown initially, shows most of the items of interest.

Buttons

Use the OK button to accept all changes to the RootCause options. Use the Cancel button to discard any changes to the RootCause options. Use the Help button to figure out what is going on and how to get things done.

RootCause Options Tab

The RootCause Options Tab is used to define a number of values that control the collection and display of that trace data.

Data Collection Options

The following options control data collection at the time the program is run. These are recorded per-workspace and translate into options on the aprobe command-line, set using the Aprobe Options Tab.

Keep logged data for N previous processes

Set the maximum number of previous or concurrent processes for which data is kept by modifying the text field labeled Keep logged data for N previous processes. This controls for how many previous processes logged data files are retained. Larger values will use more disk space. This value must be 1 or greater, resulting in two process's data being saved: the most recent run and one previous to that.

Data File Size

Set the maximum data file size by modifying the Data File Size text field. This controls how large each data file can become while logging before a new data file is created. Smaller values will lead to faster times to display data, and allow more control over the amount of data to be viewed at one time, but limit the size of tables and other monolithic data items logged by some probes.

Wraparound data logging wraps at N

Set the maximum size of wrap-around data kept in data files by modifying the text field labeled Wraparound data logging wraps at N. This controls how much data is kept in the wrap-around data files. Larger values will use more disk space. This number, divided by the Data File Size specified, yields the number of data files kept in the "APD ring" in the absence of snapshots. This corresponds to the aprobe -n argument specified in the Number of APD Files field in the Aprobe Options Tab.

Total logged data limit per process

Set the maximum size of all logged data in data files and snapshot files by modifying the text field labeled Total logged data limit per process. This controls the total amount of logged data that is retained in wrap-around data files plus older data files preserved as a result of a snapshot action. Larger values will user more disk space.

Data Display Options

The following options control the display of data though the Trace Index Dialog and the Trace Display. These options are saved as preferences on a per-user basis.

Maximum number of items in Trace Index

Set the maximum number of items allowed in the Trace Index Dialog by modifying the text field labeled Maximum number of items in Trace Index. Larger values will lead to longer times to build an index.

Maximum number of events in Trace Display

Set the maximum number of events allowed in the Trace Display event tree by modifying the text field labeled Maximum number of events in Trace Display. Larger values will lead to longer times to display event trees.

Display N data files before selected

Set the number of data files displayed before an event selected in the Trace Index Dialog by modifying the text field labeled Display N data files before selected. This controls how many events are displayed before the selected event. Larger values will lead to longer times to display data.

Display N data files after selected

Set the number of data files displayed before an event selected in the Trace Index Dialog by modifying the text field labeled Display N data files after selected. This controls how many events are displayed after the selected event. Larger values will lead to longer times to display data.

Build Options Tab

The Build Options Tab in the RootCause Options Dialog is used to set options that control how Apc files are compiled and to include additional custom Apc files. Note: these options do not apply to Java-only workspaces.

Custom APC Files

The text field marked Custom APC Files displays the name of the custom APC files to compile as part of the Build operation. Click the Edit... button to bring up Edit Source Path Dialog. There you may add or remove APC (or other) files to be included in the build.

Additional APC Options

Type any additional APC options in the text field marked Additional APC Options. Separate each option by at least one space as you would on the Apc command line.

Aprobe Options Tab

The Aprobe Options Tab is used to set options that control how Aprobe collects data from the defined traces.

APD File

Choose the name of the APD file where Aprobe collects data in the APD File text field. Any path and name ending in ".apd" can be specified here, and the APD files will be created with that name. Note that this path is ignored for remote (deployed) workspaces. This corresponds to the aprobe -d option.

Number of APD Files

Set the number of APD files that will be chained together to hold trace information in the Number of APD Files text field. Using multiple files prevents any one file from becoming too large. As each APD file fills up it is closed and a new one is opened. If the maximum number of files have been created, the oldest one is deleted. This is an APD ring. You may select 1 or more files. This corresponds to the aprobe -n option.

Size of APD Files

Set the maximum size in bytes of the APD files in the Size of APD Files text field. This value can be used to restrict the amount of information saved in each file. You can select any size from 1MB to 256MB. This corresponds to the aprobe -s option.

Number of APD Rings

Specify the number of APD file rings to be preserved in the Number of APD Rings text field. The number of APD rings determines how many Process Data Sets are preserved for the program in addition to the most recent. You need one set of rings for each simultaneous program execution you want to trace, with a minimum of 1. This corresponds to the aprobe -k option.

Number of Snapshot Files

Specify the number of snapshot data files in the Number of Snapshot Files text field. This value determines how many snapshot files are kept for hte program in addition to the wraparound APD files This corresponds to the aprobe -t option.

Additional Aprobe Options

Specify any additional options in the Additional Aprobe Options text field, just as you would on the Aprobe command line. The most commonly needed one "-qstack_size=1000000" to increase the Aprobe stack size.

Apformat Options Tab

The Apformat Options Tab is used to set options that control how the apformat command formats data collected from the defined traces and probes.

Additional Apformat Options

Specify any additional options in the Additional Apformat Options text field, just as you would on the Apformat command line.

Run Options Tab

The Run Options Tab in the RootCause Options Dialog is used to set options required to run the program on the local computer using the Run Program menu item or the Run button. These options are ignored unless your application is run directly from the RootCause GUI.

Working Directory

Set the path of the working directory where the program should run in the Working Directory text field. This also specifies the directory from which the load modules are evaluated.

Command To Invoke Program

Set the command to invoke the program in the Command To Invoke Program text field

Program Parameters

Specify any program parameters in the Program Parameters text field, just as you would on the command line.

Java Parameters

Used only for Java applications.

Source Options Tab

The Source Options Tab is used to set options that control how missing source files are handled in the Trace Setup and Trace Display dialogs.

Don't Prompt for Source Files

Check the Don't Prompt for Source Files box to specify that actions in the Trace Setup Dialog and Trace Display window are to ignore missing source files. This setting is also available in the source file prompt dialog itself. You may find source files later using the Find Source File menu item.

Edit Source Path Dialog

The Edit Source Path Dialog is opened by the Source Path item in the Setup Menu, and allows the user to edit the path used to search for source files. Source files are displayed in the Trace Setup Dialog and Trace Display to provide context information when selecting traces and viewing trace events.

The list displays, in order, the directories searched for source files if the full path recorded in the object or class file is not found.

Buttons

Add

Use the Add button to add a new path before the selected one. A file chooser will open to select the path.

Move Up

Use the Move Up button to move the selected path ahead of the path above it.

Move Down

Use the Move Down button to move the selected path behind the path below it

Remove

Use the Remove button to remove the currently selected path.

Use the OK button to accept the changes to the source path. Use the Cancel button to discard any changes to the source path. Use the Help button to figure out what is going on and how to get things done.

Custom Apc Files Dialog

The Custom Apc Files Dialog is opened by the "Edit..." button on the Custom APC Files text field in the Build Options Tab of the RootCause Options Dialog reached from the Options item in the Setup Menu. This allows the user to add, remove, or rearrange files that will be passed to the "apc" command as part of the workspace build process. Filenames are also added to this list as a side-effect of the Generate Custom APC Dialog if the Add to custom apc files checkbox is checked.

Buttons

Add

Use the Add button to add a new filename before the selected one. A file chooser will open to select the path.

Move Up

Use the Move Up button to move the selected filename ahead of the path above it.

Move Down

Use the Move Down button to move the selected filename behind the path below it

Remove

Use the Remove button to remove the currently selected filename.

Use the OK button to accept the changes to the source path. Use the Cancel button to discard any changes to the source path. Use the Help button to figure out what is going on and how to get things done.

UAL Options Dialog

The UAL Options Dialog is opened by the Edit UAL item in the Setup Menu or Workspace Tree Workspace Tree Popup Menu, or by double-clicking on a name in the UALs node node in the Workspace Tree.

This is the "default UAL plug-in" for UALs added using Add UAL. It lets you set options for UALs associated with the workspace. It is overridden by more powerful configuration dialogs for the trace and java_exceptions UALs. Contact OC Systems for more information on writing interfaces for UALs.

The UAL file and name are displayed in the text fields labeled UAL File and UAL Name. These values cannot be changed.

If a UAL requires command-line parameters at Aprobe-time or Apformat-time, you can change those values in the text fields labeled Aprobe Parameters and Apformat Parameters. The "-p" option used on the aprobe and apformat command-line to introduce UAL arguments should not be specified here.

Buttons

Use the OK button to set the Ual options as specified. Use the Cancel button to abandon the operation. Use the Help button to figure out what is going on and how to get things done.

Run Program Dialog

The Run Program Dialog is shown by the Run button (the Run Program operation) to run a traced program on the local computer. This is provided as a convenience for running simple programs. Programs that require special start-up scripts or batch files can be run from the command line in a normal fashion (as long as they have been registered with a RootCause workspace for tracing). The working directory, program path, and program parameters (as specified in the Program Options Dialog) are displayed.

Choose the Autoload Output checkbox to automatically open a Trace Data Dialog upon program termination to format and display the trace data.

Buttons

Use the OK button to run the program as specified. Use the Cancel button to abandon running the program. Use the Help button to figure out what is going on and how to get things done.

Deploy Dialog

The Deploy Dialog is opened by the Deploy button (the Deploy Program operation) to deploy the traces for a program to a remote computer so the program can be traced there. The dialog allows the user to select some final options, and to review other options.

Output file

Type the path name of the output file to be created in the text field labeled Output file or select a path using the "..." button. This is the file that must be transmitted to the remote computer for installation.

License file

Type the path name of the license file to be used in the text field labeled License file or select a path using the "..." button. This is normally $APROBE/licenses/agent_license.dat.

If the License file does not have the proper name or cannot be found an error is given and the user must provide a satisfactory file. If the file does not contain a valid license, an error is given but the user may continue and create a deploy package, but then a license must be provided at the remote site.

Aprobe Options

Use the Aprobe Options tab to inspect the Aprobe options that will be used. If they are not correct, go back to the RootCause Options Dialog to change them.

Program Options

Use the Program Options tab to verify the default path to the program with which the workspace is associated. If the path will be different in the remote environment, then the correct path will have to be specified with the rootcause register -x option when registering the .dply file on the remote computer.

UALs

Use the UALs tab to inspect which UALs will be activated when the program is traced. If they are not correct, go back to the UALs node node in the Workspace Tree of the main window to change them.

ADI Files

Use the ADI Files tab to select for which modules you want to generate Aprobe debug information (ADI) files. These files are required to support custom UALs that reference program data and types. Check the modules for which ADI files should be created and deployed. By default the executable module is already checked; ADI files may not be generated for system-defined library modules.

Buttons

Use the OK button to create the deploy file from the given parameters. Use the Cancel button to abandon the deploy operation. Use the Help button to figure out what is going on and how to get things done.

Decollect Data Dialog

The Decollect Data Dialog is opened by the Decollect button (the Decollect Collected operation) to unpack data collected on a remote computer for examination on the local computer.

When the operation completes, an Open Decollection is automatically done on the newly created directory to allow the data to be formatted and viewed.

Collect File

Type the path name of the collect file to unpack in the Collect File text field or use the "..." button to open a file chooser to select the file. This is the file that was created by a collect operation on the remote computer and transmitted to the local computer.

Destination To Create

Type the path name of the destination directory to be created in the Destination To Create text field or select a path using the "..." button. This is the directory that becomes the decollection that will contain the unpacked data on the local computer.

Buttons

Use the OK button to unpack the collect file to the chosen destination. Use the Cancel button to abandon the decollect operation. Use the Help button to figure out what is going on and how to get things done.

Trace Setup Dialog

The Trace Setup Dialog is used to set up traces and probes for the program. It consists of three parts: the Program Contents Tree on the left, the Source Pane on the upper right, and the Variables Pane and Probes Pane as tabs on the lower right. The following sections describe each of these in more detail.

Program Contents Tree

The Program Contents Tree displays the currently selected traces for the program. At the root is the program node. Under this node are the libraries (modules) against which the program has been linked. Additional dynamic modules that have been explicitly added to the workspace using Add Dynamic Module in the main Workspace Menu will also appear.

Nodes with child nodes beneath them are have a "lever" next to that node. Clicking on a "lever" next to a node in the tree, or double-clicking on node's label, will expand it, showing the immediate children of that node. Doing these actions on an already-expanded node will collapse it, hiding its child nodes. Double-click also expands or collapses a node.

Under each module are all the functions contained in that module, subdivided into directories and files based on the source file information associated with the modules. If no source file could be determined because the function was not compiled with debug information, the function is listed under the special <Unknown File> node.

Black dots next to the functions indicate that the function will be traced. Blue dots next to the functions indicate that actions such as logging are defined.

Selecting a function node will cause the source to be displayed in the source pane, if possible. In the Variables Pane, the parameters, return value, and global data that can be logged on entry to or exit from the function will be displayed. The probe triggers and actions associated with the function will be displayed in the Probes Pane.

Trace Setup Popup Menu

Operations on nodes in the Program Contents Tree are done via a popup menu. Select a node in the tree and use the right mouse button (MB3) to display the popup menu.

Trace This Item

Use Trace This Item to add a trace for the selected function node.

Don't Trace This Item

Use Don't Trace This Item to remove a trace (black dot) for the selected function node.

Enable Load Shedding for This Item

Use Enable Load Shedding for This Item to re-enable load shedding (the default action) for the selected function node. This action is available only when load shedding has been previously disabled, as indicated by a red dot.

Disable Load Shedding for This Item

Use Disable Load Shedding for This Item to disable load shedding for the selected function node. This is generally not necessary unless the function has a very high execution rate, yet you still want to trace it, at the risk of slowing the overall trace. Disabling load shedding causes the item to be marked with a red dot.

Trace All In

Use Trace All In to add a trace for all the child nodes of the selected module, file, or directory node.

Don't Trace All In

Use Don't Trace All In to remove traces (black dots) for all the child nodes of the selected module or file node.

Remove Probes For All Child Items

Use Remove Probes For All Child Items to remove any probes applied to the selected node and all its child nodes. Note that probes here are those actions indicated by the blue dots, which were added from the Variables Pane or Probes Pane.

Trace All Lines in Function

Use Trace All Lines In Function to add a trace for all the lines in the selected function node.

Don't Trace All Lines in Function

Use Don't Trace All Lines In Function to remove traces for all the lines of the selected function.

Edit Wildcards

Use Edit Wildcards to examine and change the TRACE and REMOVE directives for the module containing the selected item, using the Edit Wildcard Strings Dialog.

Find Function/Method

Use Find Function/Method to find a function or method in the program contents tree. This will open the Find In Program Contents Dialog. This is the same as the Find button at the bottom of the window.

Find Source File

Use Find Source File to locate the source file for the selected file or function.

Source Pane

The Source Pane displays the source file for the currently selected function in the Program Contents Tree. The source for the current function is annotated with line numbers and checkboxes which indicate which lines can be traced in the function. Checking a source line will cause the data (parameters and variables) that can be logged at the line to be displayed in the Variables Pane, and the applicable probe triggers and actions to be displayed in the Probes Pane.

Variables Pane

The Variables Pane displays the data items that can be logged:

  • on entry to a function;
  • on exit from a function; or
  • when a source line is reached.

When a function is selected in the Program Contents Tree, the Variables pane will show parameters and data items that can be logged on entry or exit to the function. When a Source line is checked in the Source Pane, the Variables Pane will display the data items visible from that line. Log the value of a variable by checking the box next to it.

Probes Pane

The Probes Pane displays the probes that can trigger actions:

  • on entry to a function;
  • on exit from a function; or
  • when a source line is reached.

When a function is selected in the Program Contents Tree, the Probes pane will show probes activated on entry to or exit from the function. When a Source line is checked in the Source Pane, the Probes Pane will display the probes activated when the line is reached.

When the program node in the Program Contents Tree (denoted by the letter P) is selected, the Probes Pane displays probes that can trigger actions:

  • on program entry;
  • on program exit;
  • on thread entry; or
  • on thread exit.

To define a probe, first check the "On" box on the left to activate it. Then select a trigger from the Probe Trigger options menu.

Next select an action from the Probe Action options menu. If the action requires a parameter, specify it in the Probe Parameter text field or combo box. You can disable a probe by unchecking the On check box associated with the probe.

Probe Actions

The following actions may be selected from the Probe Actions options menu:

Log Comment

Log a string literal at the given Trigger point. The Parameter to this action is the string to be printed. It will appear as a COMMENT event in the Event Trace Tree.

Log Traceback

Log a stack traceback at the given Trigger point. The Parameter is the maximum depth to trace back. The overhead of the traceback operation is proportional to this depth. It will appear as a TRACEBACK node in the Event Trace Tree.

Log Statistic

Log time or other information specified by the Parameter. The statistics appear as a Process Statistics node in the Event Trace Tree. The Parameter values are:

    • gethrtime(3C) (wall time) - calls the gethrtime() system function and displays the value returned, the elapsed time since the start of the program.
    • gethrvtime(3C) (CPU time) - calls the gethrvtime() system function and displays the value returned, the CPU time consumed by the process.
    • rusage(3C) (resource usage) - calls the rusage() system function, and displays the fields of the structure it returns.

Enable Tracing

Enable tracing that was disabled by an earlier Disable Tracing action. Has no effect if tracing was already enabled.

Disable Tracing

Disable tracing at the trigger point, to reduce the amount of data logged. It is useful to use Disable Tracing at the On Entry trigger point of a function, and Enable Tracing at the On Exit point, or vice versa, to control the data logged.

Log Snapshot

Cause a data snapshot to occur at the probe point, which also logs a SNAPSHOT event. These events are shown in the Trace Index Dialog, making them very easy to locate even if a lot of data has been logged. The "Probe Parameter" field is a text field which defaults to ROOTCAUSE_SNAPSHOT, but which may be replaced with any reasonably short text string to more uniquely identify the snapshot point.

Buttons

Find

Use the Find button to search the program contents tree for functions of interest. This will open the Find In Program Contents Dialog.

Options

Use the Options button to select advanced options that affect all traces. This opens the Global Trace Options Dialog.

Custom

Use the Custom button to generate APC files that can be customized and included with the normal traces. A function node must be selected. This specifies for which node custom APC will be generated. This opens the Generate Custom APC Dialog.

OK

Use the OK button to build a UAL from the selected trace setup, and then dismiss the Trace Setup Dialog.

Apply

Use the Apply button to build a UAL from the selected trace setup. The Trace Setup Dialog will stay visible.

Dismiss

Use the Dismiss button to close the Trace Setup Dialog without building a UAL from the trace setup.

Help

Use the Help button to figure out what is going on and how to get things done.

Find In Program Contents Dialog

The Find In Program Contents Dialog is used to search for functions containing a specific pattern, or to find a function based on its source file name and line number.

Find String

When the Find String tab is selected, you provide a string that matches all or part of a function (not a file or directory) in the Program Contents Tree. You must select a module, directory, file, or function node in the program contents tree to indicate the start of the search. The next function that contains the given search string will be selected, or a dialog will indicate that no matches were found.

Consider Case

If Consider Case is selected, the search for the given string will exactly match the case of letters in the given search string. By default lower and upper case of the same letter are considered equal.

Search All Modules

If Search All Modules is selected, then all modules will be searched without asking for confirmation after each one is searched. You can select alternate starting nodes while the search dialog is visible to direct the search.

Goto File

The Goto File tab is used to search based on a source file name, and optionally a line number, starting from the first function in the module. You provide the full or simple name of a file to search for. The name provided is compared to the end of the full pathname of the source file containing each function, so you must always provide the file extension in your search string.

Line Number

If no Line Number is specified, the first function associated with the given file is identified. If a Line Number is specified, the function containing that line in that file is found, if any, or else the function in the file whose start line is closest to the given line.

Buttons

Use the Next button to find the next occurrence of the string in a function or method node. Use the Previous button to find the previous occurrence of the string in a function or method node. Use the Goto button to find the specified line number in a file. Use the Cancel button to dismiss the search dialog. Use the Help button to figure out what is going on and how to get things done.

Global Trace Options Dialog

The Global Trace Options Dialog is used to set advanced options to control the trace and logging of data. It is opened by clicking the Options button in the Trace Setup Dialog

Dereference Pointers

The Dereference Pointers option determines whether data whose type is a pointer type has the value of the pointer (the address), or the referenced data logged. Check the option to log the referenced data.

Maximum Logged String Length

The Maximum Logged String Length text field determines how many bytes of dereferenced string types are logged. Lowering this value can reduce the amount of data logged and reduce the impact that tracing has on the program's performance.

Enable Load Shedding

This checkbox indicates whether load shedding will be enabled on the next trace. The scale and text field underneath this checkbox indicates the relative amount of tracing overhead that should be tolerated before tracing is disabled on a function. This is recorded on a per-workspace basis, and is enabled by default to allow moderate overhead.

Individual functions may be excluded from load shedding using the LOAD_SHED Table associated with a LOAD_SHED node at the end of the Trace Display.

Buttons

Use the OK button to accept the option values as displayed. Use the Cancel button to discard any changes and leave the values as they were. Use the Help button to figure out what is going on and how to get things done.

Edit Wildcard Strings Dialog

The Edit Wildcards item on the Trace Setup Popup Menu in the Program Contents Tree brings up the Edit Wildcard Strings Dialog.

The contents of this dialog reflect the Traces selected from within the Trace Setup popup menu for the currently selected module. The module to which the dialog contents apply is shown in the dialog title.

Trace Wildcards

The Trace Wildcards list on the left specifies those functions that will be traced.

Don't Trace Wildcards

The Don't Trace Wildcards list on the right shows those functions that will be explicitly removed from the list of functions to be traced, so the final set of traces is the difference between the two lists.

Add

To add a wildcard to a list, enter it in the text field below that list, then click the Add button.

Update

To replace an existing item with the contents of the text field, select that item and click the Update button.

Remove

To remove an item from the list, select that item and click the Remove button.

More Buttons

Click the OK button to save the lists as shown. Click the Cancel button to discard any changes. Click the Help button to view this text.

The names in the list are "probe names" of the form extern:"class::method(int,char*)" or "file.c":"function()"

There is only one wildcard character, '*', and '*' may appear only as the first and/or last character in the wildcard string. The following are examples of valid wildcards:

"*"
all functions in the module
M*
all functions whose name starts with M
ErrorClass::*
all methods in class ErrorClass

Note that because "extern" functions don't have the file name as part of the name, "file.c":* will only match the functions local to file.c, not the externally visible ones. To get all functions in a file you should select the filename node in the tree and choose "Trace All In filename".

Generate Custom APC Dialog

The Generate Custom APC Dialog is opened when the Custom button at the bottom of the Trace Setup dialog is clicked. It is used to generate APC files that can be edited by the user to customize the standard APC generated for probe actions.

Custom APC File

The Custom APC File text field contains the name of the file to which the APC will be generated. You can use the "..." button to select this file. This file can be edited to customize the standard actions or to add new actions. This file must be compiled to be useful, and the easiest way to do this is to name it in the Custom APC Files text field in the Build Options Tab of the RootCause Options Dialog opened by the Options item in the Setup Menu of the Workspace Browser.

Append To File

The Append To File checkbox determines whether the generated APC will be appended to the output file (to generate APC for multiple functions) or will overwrite the previous contents of the output file.

Preserve Actions In Workspace

If the Preserve Actions In Workspace checkbox is selected, the probes are added to the workspace as well as to the custom file. Note that if the custom file is then imported using the Custom APC Files text field in the Build Options Tab, such "preserved" actions may result in duplicate events being logged.

Add to custom apc files

If the Add to custom apc files checkbox is selected, the Custom APC File specified above will be added to the Custom APC Files list (if not already present) to be included in the next Build operation.

Buttons

Use the OK button to write the APC for the selected function to the indicated file. Use the Cancel button to abandon custom APC generation. Use the Help button to figure out what is going on and how to get things done.

Trace Data Dialog

The Trace Data Dialog permits the user to select the exact data files to be formated for display in the Trace Display. The user can make this choice based on the data present in each data file, to reduce the total size of the display. Data from additional workspaces can be made available for selection.

Data files available for selection are displayed in the tree labeled Trace Data Files. Check the checkbox to the left of a node in the tree to select that data file for formatting and display. Nodes in the tree represent data files collected for processes running traced applications, the RootCause Log file, or a decollected log file.

Buttons

Add Process

Use the Add Process... button to add the data files collected from another process running a traced application to the data files tree. This will open the Add Process Data Dialog to select data files. Once added, the data files can be selected for format and display.

OK

Once the data files have been chosen, click the OK button to format and display the data in a new Trace Display.

Apply

Click the Apply button to format and display the data in the original Trace Display. This is only available when the dialog is opened from a Trace Display.

Cancel

Use the Cancel button to dismiss the dialog.

Help

Use the Help button to figure out what is going on and how to get things done.

Add Process Data Dialog

The Add Process Data Dialog permits the user to select Process Data Set from either the Trace Data Dialog or Select Data Files Dialog. A Process Data Set is a directory containing all data files collected in a single run of an application. The user can navigate through the file system to select the relevant data sets. Multiple Data Sets may be available from a single directory because the file chooser searches the subdirectories of the selected directory recursively.

Look In

The directory to search can be entered in the text field labeled Look In or can be selected using the "..." button to the right of the text field.

Process Data Sets

The available data sets will be displayed in the list labeled Process Data Sets. Select a data set by clicking on it.

Process Data Set

The name of the selected data set will be displayed in the text field labeled Process Data Set.

Buttons

Once a Process Data Set has been chosen, click the OK button to add the data to the parent dialog. Use the Cancel button to dismiss the chooser. Use the Help button to figure out what is going on and how to get things done.

Trace Index Dialog

The Trace Index Dialog permits the user to generate an index for selected data files.

The index contains special marker events selected by the user. The index can allow the user to quickly find notable events in large traces and to examine all the events surrounding the marker in the Trace Display.

There is always one event in the index, corresponding to the Last Data Recorded, and which always appears first since the initial order of events is most-recent first.

Double-click on an event to immediately open a new Trace Display containing just that event and its context.

Click on an event in the table to select it for display. Use Shift-click to select a contiguous block of events. Use Ctrl-click to select multiple, non-contiguous events.

What is Indexed

The Trace Index Dialog is opened as a result of a number of different actions, which generate an index of different data:

  1. Indexing Current Workspace Data When you:
    • choose Index Process Data in the Analyze Menu; or
    • click the Index button in the Workspace buttonbar; you have chosen to display an index for the current data in the workspace. This will replace any index you have constructed already unless the data is unchanged from the last time these operations were performed.
  2. Indexing Decollected Data When you choose Open Decollection or Recent Decollections in the Workspace Menu, an index is built using the most recent data in the decollection.
  3. Re-Indexing Displayed Data When you choose Add From Index To Display in the Trace Display File Menu, the index associated with the data currently being displayed is shown. This means that you can save and modify previously constructed indexes by leaving a corresponding Trace Display window open.
  4. Indexing Selected Process Data When you:

In all cases, you can use the Select Data Files button to change the Data Files that are indexed.

Index Columns

Click on a column header in the table to sort the table by that column. Click again to reverse the order of the sort.

The following columns are shown in the Trace Index Dialog:

Time

the timestamp of the event. The newest event is shown first initially.

Application

the name of the file associated with the application. This is the same as the Program name associated with the workspace that caused the data to be recorded.

Process

the process id (PID) of the process in which the event occurred.

Thread

the Thread ID of the thread in which the event occurred. These thread IDs are internal to Aprobe, and may not correspond to those shown by other debugging tools.

Kind

the kind of event, SNAP or EXCP, corresponding to the Snapshots and Exceptions checkboxes in the Select Events Dialog. For each Process Data Set there is also one FILE kind event with the label Last Data Recorded, which is the newest event from that process.

Event

the label associated with the event. This corresponds to the Probe Parameter associated with a Log Snapshot probe, or maybe be a special value used by a predefined probe, such as (Java) EXCEPTION, C++ EXCEPTION, or Ada EXCEPTION.

Details

the first text line of details associated with the event.

Buttons

Refresh Index

Use the Refresh Index button to regenerate the index using the current selections.

Select Data Files

Use the Select Data Files... button to choose which data files are scanned to generate the index. This will open the Select Data Files Dialog.

Select Events

Use the Select Events... button to choose kind of events to include in the index. This will open the Select Events Dialog.

Find In Index

Use the Find In Index... button to find an event or events in the index that match(es) a string. This will open the Find Events Dialog.

OK

Once the events have been chosen, click the OK button to format and display the data in a new Trace Display. Alternatively, you can double-click an event to display it.

Apply

Click the Apply button to format and display the data in the original Trace Display. This is only available when the dialog is opened from a Trace Display.

Cancel

Use the Cancel button to dismiss the dialog.

Help

Use the Help button to figure out what is going on and how to get things done.

Select Data Files Dialog

The Select Data Files Dialog permits the user to select the exact data files to be scanned when generating the index in the Trace Index Dialog.

Data files available for selection are displayed in a tree. Check the checkbox to the left of a node in the tree to select that data file for indexing. Nodes in the tree represent data files collected for processes running traced applications, the RootCause log file, or a decollected log file.

Buttons

Add Process Data

Use the Add Process Data button to add the data files collected from another process running a traced application to the data files tree. This will open the Add Process Data Dialog to select data files. Once added, the data files can be selected for indexing.

Update

Once the data files have been chosen, click the Update button to generate the index and close the dialog.

Change

Click the Change button to accept the changes to the data files, close the dialog, but not generate the new index.

Cancel

Use the Cancel button to dismiss the dialog.

Help

Use the Help button to figure out what is going on and how to get things done.

Select Events Dialog

The Select Events Dialog permits the user to select the kind of events included in the Trace Index Dialog index.

Check the checkbox to the left of an event kind to select those events for inclusion in the index:

Snapshots

include SNAP events in the index, recorded by the java_exceptions UAL or by a user-inserted Log Snapshot probe.

Exceptions

include EXCP events in the index, recorded by the java_exceptions and exceptions UALs.

Buttons

Update

Once the event kinds have been chosen, click the Update button to generate the index and close the dialog.

Change

Click the Change button to accept the changes to the event kinds, close the dialog, but don't generate the new index.

Cancel

Use the Cancel button to dismiss the dialog.

Help

Use the Help button to figure out what is going on and how to get things done.

Find Text In Events Dialog

The Find Text In Events Dialog permits the user to search for events in the index which match a text string. It is launched by the Find In Index button of the Trace Index Dialog.

Search For

Enter the text string to match in Search For text field.

Consider Case

Check the Consider Case checkbox to make the search case-sensitive.

Buttons

Find

Once the search string is set, click the Find button to find the first event that matches the string. The string starts from the event following the first selected event, or from the first event in the index if no events are selected.

Find All

Click the Find All button to find every event in the index that matches the string.

Cancel

Use the Cancel button to stop the search and dismiss the dialog.

Help

Use the Help button to figure out what is going on and how to get things done.

Trace Display

The Trace Display window is used to examine detailed trace output logged for traced programs. The Trace Display is opened from the Trace Data Dialog and from the Trace Index Dialog to show data collected for specific processes. It also displays the start of each process in the RootCause Log.

The Trace Display is composed of the following parts:

These are described below.

File Menu

The Trace Display initially displays the contents of a single APD or log file.

Refresh

Choose Refresh to reformat and reload the data files or RootCause log from which the current Trace Display was built. This is useful to add the most recent events in the RootCause Log or from a data set that is still being written to.

Open Associated Workspace

Use Open Associated Workspace to open the workspace associated with a program in the RootCause log file. This menu item is only enabled if an APP_START or APP_TRACED event is selected in a RootCause log file.

Add Data Files To Display

Use Add Data Files To Display to open a Trace Data Dialog from which a different group of data files may be selected for display. This is most useful for viewing additional events before or after those currently selected. You can determine which files are currently selected by looking in the Data Files Pane at the lower right. From that dialog, you can click Apply to replace the current Trace Data events with the new ones, or OK to create a Trace Display window.

Add From Index To Display

Use Add From Index To Display to open a Trace Index Dialog from which different indexed events may be selected for display. From that dialog, you can click Apply to replace the current Trace Data events with the new ones, or OK to create a Trace Display window.

Add Selected Process Data

Use Add Selected Process Data to build an index for the data file(s) associated with the selected process. This menu item is only enabled if an APP_TRACED event is selected in a RootCause log file and data exists for the process.

Save As XML

Use Save As XML to save the current event tree as an XML file. The XML file can be processed outside of RootCause, or reloaded for later display.

Save As Text

Use Save As Text to save the current event tree as a text file. The text file can be processed outside of RootCause.

Close

When you are finished viewing the trace display use Close to close the Trace Display window.

Edit Menu

The Edit menu provides operations on nodes in the Event Trace Tree, and are also available in a Trace Display Popup Menu there.

Deselect Function In Trace Setup

While developing a trace on a local computer you may want to remove unnecessary function traces from your trace. Select a function call in the trace event tree, then use the Deselect Function In Trace Setup to remove the selected function from the trace setup.
NOTE: When used on a LINE event, this will deselect the tracing of the entire function, not just that line.

Find Function In Trace Setup

On the other hand, you may decide that there is additional data that must be collected with a particular event. Select an ENTER, EXIT, LINE, or CALL_FROM function in the trace event tree, then use the Find Function In Trace Setup menu item to open the Trace Setup Dialog with the selected function highlighted. You can then add or remove probes of logged data items.

Find Class In Trace Setup

This applies only to Java classes.
Find Source

Use the Find Source menu item to locate the source file corresponding to an ENTER, EXIT, or LINE event.

Find Function In Trace Events

You can use the Find Function In Trace Events menu item to start a search for the next or previous occurrence of the currently selected event in the Trace Display. Select the event node in the trace event tree, then use the menu item to open the Find Text in Trace Events Dialog. The search is started at the selected event.

Show Associated
Table

Some event nodes, like CALL_COUNTS, have tables of information associated with them. Select the event node and use the Show Associated Table menu item to display the data in a Table Dialog.

Find Text in Trace Events

You can use the Find Text in Trace Events menu item to search the trace event tree for events containing a given string. The details of the trace events are searched as well. The search is started at the selected event or at the first event if one is not selected.

View Menu

The trace events are initially grouped by threads, with each showing a well-formed call tree. Use the View Menu to change this.

By Threads

Use the By Threads menu item to separate the displayed events by individual threads. This will permit you to examine the flow within each thread in isolation from the others.

By Time

Use the By Time menu item to display the trace events in time order. Events from different threads and processes will be interleaved to indicate the order in which they occurred. This can help you understand the interactions between the different threads.

Step Menu

Use the Step Menu to step through the individual events in the event trace. Stepping allows you to review program execution forwards and backwards.

Step Next Forward

Use the Step Next Forward menu item to step to the next event in the forward direction.

Step Next Backward

Use the Step Next Backward menu item to step to the previous event.

Step Into Forward

Use the Step Into Forward menu item to step into the next function call in a forward (increasing time) direction. Using this menu item from the beginning of a trace will visit every trace event in the order it occurred.

Step Over Forward

Use the Step Over Forward menu item to step over the current function call in a forward direction. This can be used to skip from an ENTER node to the corresponding EXIT node, if it exists in the current trace.

Step Out Forward

Use the Step Out Forward menu item to step out of the current call to the next event in a forward direction. This can be used to get out of calls that are no longer of interest.

Step Into Backwards

Use the Step Into Backwards menu item to step into the most deeply nested previous call. This is effectively the most immediately previous event.

Step Over Backwards

Use the Step Over Backwards menu item to move backwards over a call that is not of interest. This is useful to go from an EXIT node to the corresponding ENTRY node, if it exists in the current trace.

Step Out Backwards

Use the Step Out Backwards menu item to move backwards out of the current call to the previously traced caller.

Help Menu

Use the Help menu to figure out what is going on and how to get things done.

Stepping Toolbar

The Stepping Toolbar contains a number of buttons that help you step through the trace events in sequential forward and reverse orders. These correspond to the items in the Step Menu.

The two large up and down arrows correspond to:

The next bank of six buttons are:

Find

The Find button provides quick access to the Find Text in Trace Events operation, also available from the Edit Menu and the Trace Display Popup Menu.

Event Trace Tree

The Event Trace Tree displays the trace events logged by the traced program. The tree can be displayed in two different ways, By Threads and By Time. The initial view presented is By Threads.

In the by-thread display, the tree will display one branch for each thread that was traced. Entry and exit to called functions and other events can be viewed by expanding the branches of the tree. You can use the stepping buttons to navigate through the trace events, or you can directly manipulate the trace event tree with the mouse.

In a by-time display, the tree will display slices of execution from the traced threads. Each thread slice can be expanded to display the events that occurred with that slice.

Most nodes in the tree consist of an icon, usually just a letter; followed by a label; followed by a description. Selecting most nodes also updates the contents of the Source Pane and the Event Details Pane with additional information.

The following kinds of events are displayed:

APP_START
a program was started but not traced.
APP_TRACED
a program was started and traced.
START_DISPLAYED_DATA
The start of the displayed data.
END_DISPLAYED_DATA
The end of the displayed data.
THREAD_START
the start of thread in a program.
THREAD_END
the end of a thread in a program.
PROCESS/THREAD
a thread slice.
ENTER
entry into a function or method.
EXIT
exit from a function or method.
ENTER (cont.)
the continuation of a function call trace.
CALL_FROM
the caller of the function in the immediately following ENTER node.
LINE
a source line trace.
LINE (Call)
a source line marking the caller of a function.
COMMENT
a probe logged a comment.
PROGRAM_COMMENT
a comment logged at program start.
TRACEBACK
a probe logged a traceback.
TEXT
unformatted program or probe output.
EXCEPTION
An exception-triggered snapshot
SYN_CALL_COUNTS
synthesized (event-based) call count table.
LOAD_SHED
information about functions disabled by load shedding.

In addition, there are "user event" nodes, marked with a u icon, which may have various labels. Examples of user events are program statistics inserted from the Probes Pane; exception events added by the exceptions or java_exceptions predefined UALs; and "Data File Change" events indicating the point in time where a new data file was started.

Also, there are snapshot events, indicated by a black S. This will be followed by the event name, such as EXCEPTION or ROOTCAUSE_SNAPSHOT.

Trace Display Popup Menu

Select a node in the tree and use the right mouse button (MB3) to display a popup menu. This displays the operations available in the Edit Menu:

In addition, the following operations from the File Menu are provided to operate upon APP_TRACED nodes and APP_START nodes:

Source Pane

The Source Pane displays the source file associated with the currently selected trace event in the Event Trace Tree. If the event doesn't have source associated with it, some other explanatory text may be shown.

Event Details Pane

The Event Details Pane displays additional data associated with the currently selected event in the Event Trace Tree. This includes data items logged on entry to or exit from functions and when a line is reached, and the time associated with each event. Complex details are organized as a tree; expand the branches of the details tree to view the data.

Call Stack Pane

The Call Stack Pane displays the simulated call stack for the currently selected event in the Event Trace Tree. This includes only functions that have been traced (and appear in the Event Trace Tree). The user should log tracebacks using Log Traceback in the Probes Pane of the Trace Setup Dialog to get the actual call stack.

Program Information Pane

The Program Information Pane, labeled "Program Info", displays information about the program(s) that were traced and the threads within the program(s). Each displayed APD file will be represented by a node describing the APD file, the program, the process, and the computer "HostID". Beneath each APD file will be nodes for the program start and end, and nodes for each of the threads started by the program.

If the log_env predefined UAL was selected in the Workspace Tree, the information recorded by that probe will appear in the program information pane as well.

Data Files Pane

The Data Files Pane displays the data files from which the trace was built.

Find Text in Trace Events Dialog

The Find Text in Trace Events Dialog is opened by clicking the Find button along the top of the window, or choosing Find Text in Trace Events from the Edit Menu or the Trace Display Popup Menu. It is used to search for trace events that contain a given pattern. You can select a trace event in the tree to be the starting point of the search (otherwise it starts at the first event). You specify the string to search for, and can choose to consider case when matching. The next or previous event that contains the given search string will be selected, or a dialog will indicate that no matches were found. Note that you can select alternate starting nodes while the search dialog is visible to direct the search.

Buttons

Use the Next button to find the next occurrence of the string in an event. Use the Previous button to find the previous occurrence of the string in an event. Use the Cancel button to dismiss the search dialog. Use the Help button to figure out what is going on and how to get things done.

Table Dialog

The Table Dialog is used to display table data associated with trace events, specifically the CALL_COUNTS, LOAD_SHED, events. The Table Dialog displays a description of the data at the top, the table of data in the center, and a legend at the bottom.

You can sort on a column of the table by clicking the label of that column. Click again to reverse the sort.

CALL_COUNTS Table

The Call Counts Table Dialog associated with the SYN_CALL_COUNTS nodes is the

Call Counts Table Popup Menu

The table data contains function names and the call count for each one. Select a row in the table and use the right mouse button (MB3) to display a popup menu. This provides the same operations as are available on ENTRY and EXIT nodes in the Event Trace Tree:

Buttons

Use the Dismiss button to dismiss the dialog. Use the Help button to figure out what is going on and how to get things done.

LOAD_SHED Table

The LOAD_SHED Table is associated with the LOAD_SHED 'S' node at the end of the trace events tree. This table displays information about functions for which tracing was disabled by load shedding during the previous run due to excessive overhead. Each entry shows the function that was disabled, the time at which it was disabled (to compare to other elements in the tree), and it's Status: what will happen to the function the next time it is traced from this workspace. The status may be:

Don't Trace

don't try to trace it next time (default);

Load Shed

disable if it takes too much time, (as for the previous run)

Don't Shed

trace it, and don't disable it even if overhead is high.

Only functions for which the action is Load Shed will appear in the table will appear in this table after the next trace. Those marked Don't Trace will not be traced at all and so will not appear in the trace event tree at all. And those marked Don't Shed will always be traced, regardless of overhead.

The status for all selected rows may be changed using operations in the table popup menu, described below.

The action for an individual row may be changed by clicking on the entry in the Status column. This displays an option menu from which you may select the desired status.

As with other tables, you can sort on a column of the table by clicking the label of that column. Click again to reverse the sort.

LOAD_SHED Table Popup Menu

The right mouse button (MB3) displays a popup menu to operate on selected rows in the table. You can use 'Ctrl-A' to select all items, or hold down the Ctrl or Shift keys while clicking to select multiple items in the usual way.

The popup menu provides operations unique to the LOAD_SHED table:

Don't Trace Selected Functions

Use the Don't Trace Selected Functions menu item to change the Status of the selected functions to Don't Trace. All functions marked as Don't Trace are updated in the Trace Setup Dialog when the table dialog's Update button is clicked.

Don't Load Shed Selected Functions

Use the Don't Load Shed Selected Functions menu item to change the Status of the selected functions to Don't Shed.

Load Shed Selected Functions

Use the Load Shed Selected Functions menu item to change the Status of the selected functions back to Load Shed, the default behavior. The specific point at which a function may be load shed is set in the Enable Load Shedding option of the Global Trace Options Dialog.

The popup menu also provides these standard operations from the Edit Menu:

Buttons

Use the Update button to apply any changes made to the Status fields in the table to the corresponding functions. Use the Cancel button to dismiss the dialog without making any changes. Use the Help button to figure out what is going on and how to get things done.

Platform-Specific GUI Issues

The RootCause GUI and Different JREs

The RootCause GUI is implemented in Java. Java is supported differently on different operating systems. The RootCause installation includes a JRE (Java Runtime Environment), which is used by default when the rootcause open command is run. If you would prefer to use a Java installation other than the one shipped with RootCause you may define the environment variable APROBE_JRE to point to the java program, for example:

export APROBE_JRE=$(whence java)

or

setenv APROBE_JRE /opt/j2re1_3_101/bin/java

Note that this must be Java version 1.2.2 or newer.

Solaris RootCause is shipped with two JREs to ensure that the GUI will run on all versions. You will find that Java runs best on Solaris 8 or newer, where it can use the newest JRE.

AIX version 5.1 or newer is required to run the Java 2 runtime required by the RootCause GUI and other workspace-related commands that use Java.

X-emulators: (Exceed, Reflection)

We have written the RootCause GUI in Java using the Swing components. These Swing components do not work well with X windows emulators such as Hummingbird Exceed and Reflection. We are investigating this, but the GUI is best viewed from a native Unix X display.

We have seen that if you set eXceed to use an X window manager, and start the Motif window manager (mwm) or a similar window manager on the Solaris host, this works around the common problems seen with Exceed.

To do this, go to the Exceed configuration (you can get to this by right-clicking on the Exceed button in the toolbar if it's running and selecting Tools/Configuration). Next, select Screen Definition, and in the 'Screen 0' tab, set Window Manger to be "X". Click "OK" when prompted to perform a server reset which will then close all of your X windows. Open a new Exceed X window and start the Motif windows manager by executing /usr/dt/bin/dtwm. Then launch the RootCause GUI from this window. GUI presentation should be improved, however there may be no window borders.

If the RootCause windows do not appear as described in the documentation when running with a Reflection X server, open the X Client Manager, and select Window Manager from the Tools menu. Select Microsoft Windows as the Default Local Window manager. Select Microsoft Windows desktop as the Window mode. Note that you must reset the Reflection X server for a change in the Window Mode to take effect, which will close all of your X applications. Hit OK or Apply to commit any changes you have made.

RootCause has been exercised under Reflection X Version 8, the version being shipped by WRQ as of 2001-06. These directions may or may not apply to other versions. Contact support@ocsystems.com for further details.

APROBE_WM_WORKAROUND Environment Variable

The APROBE_WM_WORKAROUND environment variable, when set to true, will stop the RootCause GUI from trying to set the location or size of shell windows. We have found that this eliminates a lot of problems when using an X-server such as Exceed to display the RootCause GUI. The default value is set to false.

Some GUI windows are not displayed correctly on a PC when using the Exceed X-server with a "native" window manager while logged onto a Solaris or Unix platform.

The problem is that, even though the GUI requests a window position or size, these "hints" are not always honored by the native window manager running on the PC. The result is often incorrect window size or placement.

If you are using a native window manager that does not honor these hints, you can set APROBE_WM_WORKAROUND to prohibit the RootCause GUI from requesting them.

APROBE_MONOSPACED_FONT Environment Variable

The APROBE_MONOSPACED_FONT environment variable allows the default monospaced font to be changed. We have found that using a different monospaced font eliminates some font problems when using an X-server such as Exceed to display the RootCause GUI.

The font assigned to this environment variable is passed through as a Java property that is used in UserPreferences. Unfortunately, it is difficult to determine the correct font to specify. We have had good results with the following alternate monospaced fonts:

APROBE_MONOSPACED_FONT=LucidaSansTypewriter-PLAIN-12

APROBE_MONOSPACED_FONT=monospaced-PLAIN12

Setting Background Colors

The properties in the rootcause.properties file, described in Chapter 7, "RootCause Files and Environment Variables", specify the background color for RootCause windows. The default is white, but you can change this to any of the Java-defined color names, or using a 6-character hexadecimal RGB value such as #FAEBD7.

Copy/Paste to/from Clipboard

The RootCause GUI is implemented in Java. Prior to JRE 1.4 the mouse-based copy and paste operations didn't work for JTextField and JTextPane classes used in RootCause. RootCause includes a version 1.4 JRE which it uses if possible, which is generally only on Solaris 8 and newer.

On earlier versions of the JRE, including the "fallback" version 1.2.2 that is also included with RootCause, there were two problems. The biggest problem was that these classes didn't have built-in support for cut/copy/paste but it could be explicitly added. We have added this explicit support for the RootCause main window's Message pane, but not for text areas like the Source pane or text fields in dialogs.

The other problem was that, even for explicitly implemented clipboard operations, 0the "clipboard" buffer that Java read from for Paste and wrote to for Copy was not the same as the "primary selection" buffer read/written by the default mouse-based operations.

There's nothing to be done about the first problem; unless you're using Solaris 8 you won't be able to copy or paste from text fields in RootCause. However, there is a workaround for the second problem:

There is an application called "xclipboard" that's standard on Solaris (in /usr/openwin/bin) that provides an interface between these two X Windows clipboards. So to copy something from the RootCause message window, one would:

  1. Start the xclipboard application
  2. Select the desired text from the RootCause message window
  3. Use the "Copy" operation in the workspace Edit Menu or Messages Pane popup menu. The copied text will appear in the xclipboard window.
  4. Use your mouse in the normal way to copy the text from the xclipboard window.
  5. Use your mouse in the normal way to paste to some other (e.g., mailer) window.

A more drastic alternative is to change your X resources to always use the same clipboard as Java does. This requires that you restart all xterms and other applications from which you might want to copy/paste, and can be cumbersome with other applications that use both kinds of clipboards such as xemacs. However, if you insist, you add the following to your X resources:

*.VT100.Translations:   #override \
\~Shift \~Ctrl  \~Meta  <Btn1Up>: select-end(CLIPBOARD) \n\
\~Shift \~Ctrl  \~Meta  <Btn2Up>: insert-selection(CLIPBOARD) \n



Copyright 2006-2017 OC Systems, Inc.

Next Previous Index Top