[Next] [Previous] [Top] [Contents] [Index]
RootCause
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.
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:
the Workspace Tree on the left side;
the Message Pane on the right side;
the menu bar across the top; and
the Toolbar below the menu bar.
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.
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:
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.
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.
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.
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.
Enable the java_exceptions predefined UAL to trace Java 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. In addition, some Java run-time exceptions will cause a snapshot to be taken as well. The actions associated with specific Java exceptions may be specified using the Java Exceptions Configuration Dialog.
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".
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.
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.
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.
The Workspace Menu is the leftmost menu in the Workspace Browser window and contains many fundamental operations.
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.
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.
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.
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.
Choose Close to close the workspace without exiting RootCause. You will be asked if you want to save the workspace, if it is needed.
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.
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.
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.
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.
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.
The RootCause registry defines what workspaces apply to which applications. You can list the current contents of the RootCause registry with List RootCause Registry.
The current workspace can be registered with its corresponding program or class using Register Program.
You can remove the RootCause registry entry for the current workspace/program with Unregister 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 method/data no longer exists in the program.
Any number of runtime-loaded dynamic modules 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. You can choose either a class file or JAR file to be the program. You can add other class files or JAR files as dynamic modules. If you have a C++ license also, you can also add shared libraries to trace JNI calls as well.
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 method/data no longer exists in the 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.
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 J2EE Support" for more information.
Choose Exit to terminate the RootCause GUI. You will be asked if you want to save the workspace, if it is needed.
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.
Choose Cut to cut the selected text from the message pane and copy it to the system clipboard.
Choose Copy to copy the selected text from the message pane to the system clipboard.
Choose Paste to paste text from the system clipboard into the message pane at the current cursor position.
Choose Delete to delete the selected text from the message pane.
Once you have chosen a workspace and defined the program configuration, you can use the items in the Setup Menu to set up options.
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.
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.
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 Java Exceptions Configuration 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.
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.
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.
Choose Options to open the RootCause Options Dialog, from which most workspace configuration items are selected.
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.
Choose Class Path to set up the class path for Java program. This will define where the Java Virtual Machine (JVM) searches for class and JAR files. The class path is used only for Java programs. This will open the Edit Class Path Dialog.
Choose JRE Path to set up the path to the Java Runtime Environment. This determines which Java Virtual Machine will be used to run your Java program when run from the Execute menu within RootCause. The JRE path is used only for Java programs. This will open the Java Path Dialog.
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.
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.
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.
Once you have run your program with the traces you specified, you can analyze the logged 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.
Choose Examine Process Data to examine the most recently logged data in the workspace. This will open the Trace Data Dialog.
Use the Help Menu to figure out what is going on and how to get things done.
Use the Toolbar to access common menu items quickly.
Choose Setup to set up traces. This will open the Trace Setup Dialog.
Choose Build to compile the trace setup in preparation for running the program locally or deploying the traces to a remote computer.
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.
Choose Deploy to deploy the traces to a remote computer. This will open the Deploy Dialog.
Choose Decollect to unpack data collected from a remote computer. This will open the Decollect Data Dialog.
Choose Index to build an index for the most recently logged data in the workspace. This will open the Trace Index Dialog.
Choose Examine to examine the most recently logged data in the workspace. This will open the Trace Data Dialog.
The New Workspace Dialog permits the user to create a new workspace. A single Java file is associated with each workspace. If you have a license for both Java and C++, two tabs will be visible; select the tab corresponding to the kind of workspace needed. This user's guide describes only the Java workspace.
The Java file name can be entered in the text field labeled Java File or can be selected using the "..." button to the right of the text field. The Java file can be either a Java .class or.jar file. If a .jar file is selected, the main class name must be specified if it cannot be determined from the manifest.
The workspace name can be entered in the text field labeled Workspace File or can be selected using the "..." button to the right of the text field. If the user selects a workspace name that is an existing file, the will prompt for permission to overwrite the file. A default workspace name will be chosen based on the Java file or class name and the current working directory at the time RootCause was started.
The main class name can be entered in the text field labeled Class Name. The main class must exist in the .jar file. If the .jar file contains a manifest, the main class will default to the one specified by the manifest.
The class path can be specified in the Class Path text field or it can be edited using the "..." button to the right of the text field. This will open the Class Path Dialog to edit the path. The class path value will be used to find the specified Java class if no Java file name is specified.
The JRE path can be specified in the JRE Path text field or it can be edited using the "..." button to the right of the text field. This will open the Java Path Dialog to select the path. The JRE path value will be used to find the Java Virtual Machine to run the Java program.
The Working Directory field indicates the current directory when the java command was run. This is needed in order to correctly evaluate relative path names in the Class Path.
The J2EE Server Directory can be entered or browsed to using the "..." button to the right of the text field. Enter the directory where deployable Enterprise Java Bean (EJB) and Servlet classes and jars reside. RootCause will automatically add EJB and Servlet classes and jars that are specified in any J2EE compliant XML deployment descriptors. For more information see "RootCause J2EE Support".
Once valid workspace parameters have been selected, click the OK button to create the workspace. Use the Cancel button to dismiss the dialog without creating a new workspace. Use the Help button to figure out what is going on and how to get things done.
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.
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.
If the program is a Java JAR file, the main class must be specified. The main class name can be entered in the text field labeled Main Class. The main class must exist in the JAR file. The field will be initialized with the current main class.
Once a valid Java main class 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.
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.
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. The Java Exceptions Configuration Dialog is an example of such a plug-in class.
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.
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.
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.
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.
Check the box labeled Requires Trace UAL if the new UAL requires that the Trace UAL be active when it is active.
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
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.
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.
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.
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.
The RootCause Options Tab is used to define a number of values that control the collection and display of that trace data.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The Aprobe Options Tab is used to set options that control how Aprobe collects data from the defined traces.
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.
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.
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.
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.
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.
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.
The Apformat Options Tab is used to set options that control how the apformat command formats data collected from the defined traces and probes.
Specify any additional options in the Additional Apformat Options text field, just as you would on the Apformat command line.
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.
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.
This is the main class name that will appear on the Java command; do not change it. If you need to run the program with something other than the "java" command you cannot use the Run button or menu item.
Specify any program parameters in the Program Parameters text field, just as you would on the command line.
Specify any parameters to the Java Virtual Machine (JVM) in the Java Parameters text field as you would on the command line.
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.
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.
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.
Use the Add button to add a new path before the selected one. A file chooser will open to select the path.
Use the Move Up button to move the selected path ahead of the path above it.
Use the Move Down button to move the selected path behind the path below it
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.
The Edit Class Path Dialog is opened by the Class Path item in the Setup Menu, and allows the user to edit the path searched for classes found in the Trace Display events, and also when running Java using the Run button.
The list displays, in order, the directories and/or JAR files that are searched by RootCause or the JVM itself.
Use the Add button to add a new path before the selected one. A file chooser will open to select the path.
Use the Move Up button to move the selected path ahead of the path above it.
Use the Move Down button to move the selected path behind the path below it
Use the Remove button to remove the currently selected path.
Use the OK button to accept the changes to the class path. Use the Cancel button to discard any changes to the class path. Use the Help button to figure out what is going on and how to get things done.
The Java Path Dialog is opened by the JRE Path item in the Setup Menu, and edits the path to the Java Runtime Environment (JRE) used to execute Java programs.
Type the full path to the JRE root directory in the text field labeled JRE Path, or use the "..." button to open a file chooser to select the path.
Use the OK button to accept the changes to the JRE path. Use the Cancel button to discard any changes to the JRE path. Use the Help button to figure out what is going on and how to get things done.
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.
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.
The java_exceptions predefined UAL in the Workspace Tree includes a "configuration plug-in" interface which allows the user to change the default actions associated with Java exceptions when the Java Exceptions UAL is enabled. This dialog is opened by double-clicking on the java_exceptions label, or selecting Edit UAL from the Workspace Tree Popup Menu or the Setup Menu.
There are two levels of exception reporting provided, "Logging" and "Snapshots".
When an exception is Logged, an Exception event and traceback is logged which appears in the Trace Index Dialog if Exception events are selected in the Select Events Dialog, and an Exception marker appears in the Trace Display.
When an exception Snapshot is taken, in addition to the simple event logged, a snapshot event is created, which also appears in the Trace Index Dialog.
By default, all user-defined exceptions are Logged. In addition, common Java Runtime and RMI exceptions have Snapshots taken by default.
The Java Exceptions Configuration Dialog allows changing these defaults. There are two main panes in the dialog, one for Logging and one for Snapshots.
Within the Logging Exceptions pane, exceptions can be excluded from logging by adding the full Java exception class name on a separate line of the multi-line text field.
Within the Exception Snapshots pane, there are three sub-panes:
The first, labeled Default, allows turning on or off of snapshots for Runtime and RMI exceptions. The default is "on" (checked) for both types.
The second sub-pane under Exception Snapshots is labeled Include, which allows the addition of individual exception classes for which a snapshot is to be taken. Specify the full name of each exception to be included on a separate line.
Finally, the Exclude sub-pane identifies individual exception classes for which a snapshot is not to be taken. Specify the full name of each exception to be excluded on a separate line.
Use the OK button to update the configuration to be applied to the next run of the program. Use the Cancel button to abandon any changes to the workspace options.
Note: No configuration dialog is available for exceptions due to the much more limited use of exceptions in C++. However this plug-in mechanism is designed to allow site-specific configuration and extension. Contact OC Systems for more information about such customizations.
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.
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.
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.
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.
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.
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.
Use the Program Options tab to verify the default path to the program with which the workspace is associated. The name of the program file is not referenced in the remote environment, but the name of the main class within it must be the same
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.
Use the ADI Files tab to select for which modules you want to generate Aprobe debug information (ADI) files. Only compiled modules are listed here -- none are needed for Java.
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.
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.
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.
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.
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.
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.
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.
Java program contents are organized as follows:
P Main Class - the program node based on main class name
M Root Java Module ($java$) - root of all Java methods
J Class Path Element - JAR or directory in classpath
Package Element - e.g., com or sun, if applicable
C Class - a class in the parent JAR/directory/package
m Method in Class
Class Path elements are listed in alphabetical order, not the order the appear in the classpath. Use the Edit Class Path Dialog to view or change the run-time order. The Class Path element is not significant in a Trace All In operation, only the package and class names. So selecting the "com" node under petstore.jar and clicking Trace All In com will really trace all classes in all packages that start with com in the whole application, not just those in petstore.jar.
Static constructor methods have names <clinit>() and user-defined constructors are <init>(args).
Black dots next to the methods indicate that the method will be traced. Blue dots next to the methods indicate that actions such as logging are defined.
Selecting a method node will cause the source to be displayed in the source pane, if possible. In the Variables Pane, a single checkbox for logging all the parameters will be displayed. The probe triggers and actions associated with the method will be displayed in the Probes Pane.
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.
Use Trace This Item to add a trace for the selected method node.
Use Don't Trace This Item to remove a trace (black dot) for the selected method node.
Use Enable Load Shedding for This Item to re-enable load shedding (the default action) for the selected method node. This action is available only when load shedding has been previously disabled, as indicated by a red dot.
Use Disable Load Shedding for This Item to disable load shedding for the selected method 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.
Use Trace All In to add a trace for all the child nodes of the selected module, file, directory or class node.
Note: Any enclosing JAR or directory is not significant in a Trace All In operation, only the package and class names. So selecting the "com" node under petstore.jar and clicking Trace All In com will really trace all classes in all packages that start with com in the whole application, not just those in petstore.jar.
Use Don't Trace All In to remove traces (black dots) for all the child nodes of the selected module or class node.
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.
Use Trace All Lines In Function to add a trace for all the lines in the selected method node.
Use Don't Trace All Lines In Function to remove traces for all the lines of the selected method.
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.
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.
Use Find Source File to locate the source file for the selected class or method.
The Source Pane displays the source file for the currently selected method in the Program Contents Tree. The source for the current method is annotated with line numbers and checkboxes which indicate which lines can be traced in the method. Checking a source line will cause the applicable probe triggers and actions to be displayed in the Probes Pane.
The Variables Pane displays the parameters that can be logged:
When a method is selected in the Program Contents Tree, the Variables pane will show that parameters can be logged on entry to a method, which also implies logging the return value on exit.
The Probes Pane displays the probes that can trigger actions:
When a method is selected in the Program Contents Tree, the Probes pane will show probes activated on entry to or exit from the method.
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.
The following actions may be selected from the Probe Actions options menu:
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 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 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 that was disabled by an earlier Disable Tracing action. Has no effect if tracing was already enabled.
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 method, and Enable Tracing at the On Exit point, or vice versa, to control the data logged.
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.
Use the Find button to search the program contents tree for methods of interest. This will open the Find In Program Contents Dialog.
Use the Options button to select advanced options that affect all traces. This opens the Global Trace Options Dialog.
Use the Custom button to get a template of the probe deployment descriptor corresponding to your custom Java file. This opens the Generate Custom XMJ Dialog. There is no further automated support for including custom Java. See Chapter 11, "Custom Java Probes".
Use the OK button to build a UAL from the selected trace setup, and then dismiss the Trace Setup Dialog.
Use the Apply button to build a UAL from the selected trace setup. The Trace Setup Dialog will stay visible.
Use the Dismiss button to close the Trace Setup Dialog without building a UAL from the trace setup.
Use the Help button to figure out what is going on and how to get things done.
The Find In Program Contents Dialog is used to search for methods containing a specific pattern, or to find a method based on its source file name and line number.
When the Find String tab is selected, you provide a string that matches all or part of a method in the Program Contents Tree. You must select a module, class, or method node in the program contents tree to indicate the start of the search. The next method that contains the given search string will be selected, or a dialog will indicate that no matches were found.
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.
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.
The Goto File tab is used to search based on a source file name, and optionally a line number, starting from the first method 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 method, so you must always provide the file extension in your search string.
If no Line Number is specified, the first method associated with the given file is identified. If a Line Number is specified, the method containing that line in that file is found, if any, or else the method in the file whose start line is closest to the given line.
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.
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
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.
The Log Java Class Loads option determines whether each load of a Java class in the application is logged. This is enabled by default, and adds little overhead, but you may want to disable it if these events aren't helpful.
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.
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 method This is recorded on a per-workspace basis, and is enabled by default to allow moderate overhead.
Individual methods may be excluded from load shedding using the LOAD_SHED Table associated with a LOAD_SHED node at the end of the Trace Display.
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.
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.
The Trace Wildcards list on the left specifies those methods that will be traced.
The Don't Trace Wildcards list on the right shows those methods that will be explicitly removed from the list of methods to be traced, so the final set of traces is the difference between the two lists.
To add a wildcard to a list, enter it in the text field below that list, then click the Add button.
To replace an existing item with the contents of the text field, select that item and click the Update button.
To remove an item from the list, select that item and click the Remove button.
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
"class::method(String)"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:
"*"M*ErrorClass::*The Generate Custom XMJ Dialog is opened when the Custom button at the bottom of the Trace Setup dialog is clicked. It presents a text dialog describing how to construct a custom probe, including the exact XMJ text applicable to the selected mehod. See Chapter 11, "Custom Java Probes" for more information.
The New Class Dialog is opened when an attempt to find a class in the Trace Setup dialog fails. Use this dialog to enter the path for class file to be added to the Trace Setup. You can browse for .class and .jar files that match the class name. If the class name field is already filled in, you will not be able to modify it. If a matching class file was found in the classpath, it will be automatically displayed but you may browse to a different one if necessary.
Use the OK button to select the class file. Use the Cancel button to close the dialog without selecting a class file. Use the Help button to figure out what is going on and how to get things done.
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.
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.
Once the data files have been chosen, click the OK button to format and display the data in a new Trace Display.
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.
Use the Cancel button to dismiss the dialog.
Use the Help button to figure out what is going on and how to get things done.
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.
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.
The available data sets will be displayed in the list labeled Process Data Sets. Select a data set by clicking on it.
The name of the selected data set will be displayed in the text field labeled Process Data Set.
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.
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.
The Trace Index Dialog is opened as a result of a number of different actions, which generate an index of different data:
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.
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.
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.
Indexing Selected Process Data
When you:
choose Add Selected Process Data in the Trace Display File Menu or the Trace Display Popup Menu (when an APP_TRACED event is selected); or
double-click on a Data node in the Workspace Tree;
the data associated with the selected process is indexed.
In all cases, you can use the Select Data Files button to change the Data Files that are indexed.
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:
the timestamp of the event. The newest event is shown first initially.
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.
the process id (PID) of the process in which the event occurred.
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.
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.
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.
the first text line of details associated with the event.
Use the Refresh Index button to regenerate the index using the current selections.
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.
Use the Select Events... button to choose kind of events to include in the index. This will open the Select Events Dialog.
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.
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.
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.
Use the Cancel button to dismiss the dialog.
Use the Help button to figure out what is going on and how to get things done.
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.
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.
Once the data files have been chosen, click the Update button to generate the index and close the dialog.
Click the Change button to accept the changes to the data files, close the dialog, but not generate the new index.
Use the Cancel button to dismiss the dialog.
Use the Help button to figure out what is going on and how to get things done.
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:
include SNAP events in the index, recorded by the java_exceptions UAL or by a user-inserted Log Snapshot probe.
include EXCP events in the index, recorded by the java_exceptions and exceptions UALs.
Once the event kinds have been chosen, click the Update button to generate the index and close the dialog.
Click the Change button to accept the changes to the event kinds, close the dialog, but don't generate the new index.
Use the Cancel button to dismiss the dialog.
Use the Help button to figure out what is going on and how to get things done.
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.
Enter the text string to match in Search For text field.
Check the Consider Case checkbox to make the search case-sensitive.
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.
Click the Find All button to find every event in the index that matches the string.
Use the Cancel button to stop the search and dismiss the dialog.
Use the Help button to figure out what is going on and how to get things done.
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:
the menu bar and the Stepping Toolbar across the top;
the Event Trace Tree on the left side;
the Source Pane on the upper right;
the Event Details Pane, the Call Stack Pane, the Program Information Pane, and the Data Files Pane on the lower right.
These are described below.
The Trace Display initially displays the contents of a single APD or log file.
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.
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.
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.
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.
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.
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.
Use Save As Text to save the current event tree as a text file. The text file can be processed outside of RootCause.
When you are finished viewing the trace display use Close to close the Trace Display window.
The Edit menu provides operations on nodes in the Event Trace Tree, and are also available in a Trace Display Popup Menu there.
While developing a trace on a local computer you may want to remove unnecessary method traces from your trace. Select a method 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.
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 method in the trace event tree, then use the Find Function In Trace Setup menu item to open the Trace Setup Dialog with the selected method highlighted. You can then add or remove probes of logged data items. If the class containing the method cannot be found, the New Class Dialog is presented to allow the user to locate the file in which the class is defined.
To move to the node in the Trace Setup tree corresponding to the Java class containing the method in a CALL node, select the method in the trace event tree, then use the Find Class In Trace Setup menu item to open the Trace Setup Dialog with the selected method highlighted. You can then add or remove probes of logged data items. If the class cannot be found, the New Class Dialog is presented to allow the user to locate the file in which the class is defined.
Use the Find Source menu item to locate the source file corresponding to an ENTER, EXIT, or LINE event.
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.
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.
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.
The trace events are initially grouped by threads, with each showing a well-formed call tree. Use the View Menu to change this.
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.
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.
Use the Step Menu to step through the individual events in the event trace. Stepping allows you to review program execution forwards and backwards.
Use the Step Next Forward menu item to step to the next event in the forward direction.
Use the Step Next Backward menu item to step to the previous event.
Use the Step Into Forward menu item to step into the next method 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.
Use the Step Over Forward menu item to step over the current method 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.
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.
Use the Step Into Backwards menu item to step into the most deeply nested previous call. This is effectively the most immediately previous event.
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.
Use the Step Out Backwards menu item to move backwards out of the current call to the previously traced caller.
Use the Help menu to figure out what is going on and how to get things done.
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:
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.
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 methods 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:
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.
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:
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.
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 methods 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.
The Call Stack Pane displays the simulated call stack for the currently selected event in the Event Trace Tree. This includes only methods 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.
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.
The Data Files Pane displays the data files from which the trace was built.
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.
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.
The Table Dialog is used to display table data associated with trace events, specifically the CALL_COUNTS, LOAD_SHED, and JAVA_CLASS_LOADS 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.
The Call Counts Table Dialog associated with the SYN_JAVA_CALL_COUNTS nodes is the
The table data contains method 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:
In addition, the operation
Find Class in Trace Events
is provided to search from the start of the event tree for the class name using the Find Text in Trace Events Dialog.
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.
The Java Class Loads Table Dialog is associated with the JAVA_CLASS_LOADS node near the end of the event tree.
The table data contains class names. Select a row in the table and use the right mouse button (MB3) to display a popup menu. This provides the following operations:
Find Class in Trace Events
is provided to search from the start of the event tree for the class name using the Find Text in Trace Events Dialog.
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.
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 methods for which tracing was disabled by load shedding during the previous run due to excessive overhead. Each entry shows the method 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 method the next time it is traced from this workspace. The status may be:
don't try to trace it next time (default);
disable if it takes too much time, (as for the previous run)
trace it, and don't disable it even if overhead is high.
Only methods 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.
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:
Use the Don't Trace Selected Functions menu item to change the Status of the selected functions to Don't Trace. All methods marked as Don't Trace are updated in the Trace Setup Dialog when the table dialog's Update button is clicked.
Use the Don't Load Shed Selected Functions menu item to change the Status of the selected functions to Don't Shed.
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 method 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:
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.
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.
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.
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.
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
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.