[Next] [Previous] [Top] [Contents] [Index]

RootCause

RootCause Demo

This demonstration program, included as part of the RootCause installation, has been designed to provide an introduction and overview of the RootCause product. The program is:

%APROBE%\Demo\RootCause\Java\Pi.class

It is a simple Java program, which computes the value of Pi by iteration using multiple threads. You can find the source in the same directory as the class file.

In this demonstration the goal is to provide an overview of the whole RootCause process, showing initial definition and tuning of the trace, then collection of detail about a specific function.

Set Up

Before running this RootCause Demo, you must install and set up to use RootCause as described in Chapter 4, "Getting Started". This will define the APROBE environment variable which is necessary to use RootCause.

In the instructions that follow, we'll use %APROBE% to refer to the path where RootCause is installed, generally \Program Files\OC Systems\RootCause.

Use a Supported JRE

Note that only Version 1.2 or higher of the Java runtime environment (JRE) is supported. You can verify this by typing "java -version". If it says something like java version "1.1.6" then that will NOT work. You can download a newer version from java.sun.com. For the purposes of this evaluation, you can use the JRE shipped with RootCause by adding

%APROBE%\java_rte\bin

to your PATH using Start->Control Panel->System->Environment.

Define a Shortcut to the Demo

The demo is a command-line program, but can be run from the Desktop via a shortcut. To create a Desktop shortcut:

On the Desktop right-click to bring up the context menu, choose New->Shortcut to bring up the Windows New Shortcut wizard.
Type or Browse to the path containing the script that runs the program:
APROBE\Demo\RootCause\Java\Pi.cmdthen click Next in the Wizard.

Note APROBE must be the actual path to the installation -- you can't use the environment variable %APROBE% here.
Click Finish to create a shortcut called Pi.cmd.

Open the RootCause GUI

Double-click on the RC icon on the Desktop, or choose RootCause->RootCause from the Start menu to start the RootCause GUI.

The RootCause Workspace Browser window will come up, and also a Trace Display window showing the contents of the RootCause Log. You can close the RootCause Log window; we'll look at it more closely later.

The Workspace Browser window is empty, since we've not started developing a trace yet, but the RootCause On checkbox is available to enable the logging of applications on the machine.

Click the RootCause On checkbox.

Run With RootCause

If you created the desktop shortcut for Pi.cmd as described in "Set Up" above, just double-click to run the program. A text window pops up with the output of this console application, printing some diagnostics and the value of Pi computed by two threads. Hit Enter in the window to close it.

Click RootCause On to clear the checkbox and turn off logging until we're ready to run again. Checking the RootCause On checkbox enables the automatic logging of every process that is started, and clearing the checkbox in the GUI disables this logging. Later, we'll show that when the Pi class is registered with the RootCause workspace, it will be traced according to your specifications as well as simply being logged.

View the RootCause Log

To see the effect of running the program with RootCause "On", type Ctrl-L in the Workspace Browser window, or choose Open RootCause Log from the Workspace Menu.

The Trace Display window shown when you first started RootCause will be shown again. This window is the RootCause Trace Event Display window for viewing all trace events. On the left is the Event Tree; on the upper right is the source/text window; and on the lower right is the "details" window. In the text window you will see some information about the log file.

Locate the APP_START event (in the Trace Event window) associated with the Pi application run earlier. To view information about this event, select the APP_START node in the event tree with a left click (MB1). This will fill in "details" about that event in the lower right window.With the APP_START Pi node highlighted, right-click (MB3) to bring up the Trace Display Popup Menu.

Click Open Associated Workspace on the popup-menu on the Pi event.

This will open a New Workspace Dialog with the program name and default workspace filled in.

This combination: selecting a node in the tree, then using the popup menu to choose an operation, is the basic way of working within RootCause.

Open a RootCause Workspace

To complete the creation of a RootCause workspace for Pi:

Click Ok in the New Workspace dialog to complete the creation of the workspace.

Click Yes to confirm that you want to register the Pi class with this workspace. This registration is how RootCause determines what applications to trace.

You may close the RootCause Log window opened in the previous step.

You now see the RootCause Workspace Browser. This is described in detail in Chapter 8, "RootCause GUI Reference".

Define the Trace

There are several aspects to a RootCause trace:

Predefined UALs selected from the Workspace Tree;
Method and Line traces selected from the Trace Setup Dialog;
Probes to gather or preserve data, also selected in the Trace Setup Dialog; and
User-writen Custom probes as described in Chapter 11, "Custom Java Probes".

In this part of the demo we illustrate the use of Predefined UALs and tracing method calls; then we'll return to the Trace Setup Dialog to add some probes. Custom probes are an advanced feature not presented here.

In the RootCause GUI main window, opened in the previous section:

Enable a UAL

Under the UALs node in the Workspace Tree:

Check the checkbox next to predefined UAL labeled java_exceptions.dll, as highlighed in the figure above. Simply checking this box will report all user-defined and many predefined Java exceptions.

Define Method Traces

Now we'll add traces specific to this application.

Click on the Setup button in the button bar.

This will open the Trace Setup Dialog, showing the modules of the application in the Program Contents Tree. The Program Contents Tree identifies the modules, directories, packages, classes and methods in the program, and allows you to specify complex actions on each method. See "Java Program Contents" for a description of the Java hierarchy.

For this demo we'll first just specify a trace on all methods in the Pi class, then return later to add data and probes.

Click on the "lever" icon next to the M Root Java Module node to expand it. You'll see the directories in the class path under this.
Similarly, expand the first J node, which should be the RootCause\Demo\RootCause\Java directory from the classpath. You should now see the C Pi node, representing the Pi class.
Click on the C Pi node to select it, then right-click to see the popup menu for this class.
Click Trace All In Pi.
Click the OK button at the bottom right of the dialog to record the trace and dismiss the Trace Setup dialog.

Trace With RootCause

Repeat the steps performed previously in "Run With RootCause" to launch the Pi application:

Click the RootCause On checkbox to enable logging.,
Double-click on the Pi.cmd shortcut to run the application, then
Type Enter in the Pi MS-DOS window to close it.

This time, since the program is registered with a workspace, it will be traced as specified in the workspace, and the resulting output will be recorded within the workspace. There will be some startup delay, but if you notice that the program runs slower once started, this is probably because your workspace is being accessed across the network from your machine. See "RootCause and Efficiency Concerns".

View The Data Index

We're now ready to view the data generated by running with our Trace. This is discussed in detail in "RootCause Data Management".

In the Workspace Browser window, do the following:

Click the Index button. This will bring up the Trace Index Dialog for the most recently generated data.
In the Trace Index Dialog, click the Select Events button.

In the Trace Index Dialog, double-click on the second item in the table, the first item with an Event name of EXCEPTION.

This will open a Trace Display Dialog centered at that EXCEPTION snapshot event.

Examine and Revise the Trace

The EXCEPTION trace event selected from the index should appear highlighted in the Trace Display. This was a result of checking "java_exceptions" under "Enable a UAL" above.

You see that the exception occurred within the method Pi::calc_pi from the preceding ENTER node, and see that it occurred before the method Pi.ataninvint was entered. These ENTER and EXIT nodes are a result of the "Trace All In Pi" action added under "Define Method Traces" above.

Use the up-arrow key to go the preceding event labeled "Exception" (in mixed case) to see more information about the exception in the Event Details Pane in the lower right, as shown above.

If you scroll to the top of the Event Trace, you will see a number of threads. The first is the main thread of the Java application; the last two are those created by the application to compute Pi; the rest are created by the JVM itself and contain no traced calls.

The event tree is a call tree, and can be very useful. From an ENTER or EXIT node in the tree you can use the Trace Display Popup Menu to:

remove the called method from the set of methods to be traced,
find the next reference to the same method in the trace events, or
go to the method in the Trace Setup Dialog to trace additional information.

As you step to each event, the Event Details Pane may show additional information about that event. See "Trace Display" for a more complete description of this window.

Take some time to explore the event tree. Then we will look at using the information available here to revise or " tune" the trace used in the next run.

Call Counts

Useful information about the methods called in your program may be obtained by looking at the call frequency as shown in the CALL_COUNTS table.

Select (left-click) the SYN_JAVA_CALL_COUNTS node, near the end of the event tree.
Right-click (with MB3) to show the Call Counts Table Popup Menu on this node.
Click Show Associated Table. This will open a table listing each called method and the number of times it was called.
Select (left-click) the "Pi::<init>" entry in the call count table.
Right click to show the popup menu.
Select Deselect Function In Trace Setup in the popup menu.

You can also Find Function In Trace Events to search for methods in the call tree, and remove them from there.

When you've finished making changes to the trace, click the Dismiss button at the bottom of the SYN_JAVA_CALL_COUNTS table window, and then
Click the Build button in the main window.
Notice the effects of removing these calls in the next trace we generate.

NOTE: In most "real" programs, high-overhead functions selected for tracing are automatically identified and disabled via load shedding, and are listed in the LOAD_SHED Table associated with the LOAD_SHED node at the end of the event tree. This demo doesn't run long enough for the load shedding heuristics to apply. See "RootCause Overhead Management" for a general discussion of load shedding.

Tracing The Details

So far we have seen how the RootCause process works by:

enabling a predefined UAL (java_exceptions);
defining a simple trace from the Trace Setup Dialog;
running the application under RootCause;
choosing an event in the Trace Index Dialog;
viewing events in the Trace Display; and
modifying the trace by selecting methods from the call counts table.

RootCause allows you to record much more than the entry and exit of methods and threads. You can record data values and insert probes as well.

Open Trace Setup

Click the Setup button in the Workspace Browser to return to the Trace Setup Dialog.

This is just as in "Define the Trace" above, but this time we'll record some details about a specific method, Pi::ataninvint, rather than tracing everything.

Select A Single Method

Expand the Pi class node to see the methods;
Select the ataninvint method. This will bring up the source code for this method in the Source Pane, and show a Log Parameters checkbox in the Variables Pane.

Log Parameters

Check the Parameters checkbox.

Add a Snapshot Probe

In that same lower-right area, click on the Probes tab to show the Probes Pane. Probes in this context are special actions that can be performed at points in the currently selected method.
Click the "On" checkbox.
Where it says No Trigger, select Function Entry.
Where it says No Action, select Log Snapshot (this is the last item in the dropdown menu, so you may have to scroll down).
Where it says ROOTCAUSE_SNAPSHOT, select this and type in "My Snapshot" and hit Enter.

We've now requested that all parameter values be logged (recorded) on entry to method Pi::ataninvint, and also that a data snapshot be taken at this point and marked with the Event Name "My Snapshot".

Note: A snapshot causes data which might otherwise be deleted do to "data wraparound" to be preserved. In this small demo, a snapshot is not really necessary since it doesn't generate enough data to wrap around and cause old data to be lost. See "Data Snapshots" for more information.

Record and Compile the Trace

Click the OK button at the bottom right of the dialog to save and build the trace and dismiss the Trace Setup dialog.

Run With RootCause

Again, check that RootCause On is enabled, and run the application by double-clicking on the desktop icon Pi.cmd, as described in "Trace With RootCause".

Index the New Trace

Click the Index button in the Workspace Browser window.
In the Trace Index Dialog that comes up, double-click on the SNAP entry labeled "My Snapshot" to go right to where our new probes were added.
Select the "ENTER ataninvint" node immediately preceding the Snapshot node to see the Parameter values on entry.

Find the Calls Of Interest

The Trace Display window opened from the Trace Index Dialog operation will contain many events, including other calls to ataninvint.

With the "ENTER ataninvint" node selected, right-click to show the Trace Display Popup Menu and choose Find Function In Trace Events.
This will bring up the Find Text in Trace Events Dialog with the current method name filled in. Click Next, and the next occurrence of this string will be selected. Thereafter you can continue clicking Next, or enter any other string to search for. You can use Find Text in Trace Events from any the popup or Edit menu to search for any string in the current Trace Display.

Where To From Here?

This chapter should have given you a good overview of the process of developing a trace and gathering data for a program. Now you're ready to try it on your own application.