[Next] [Previous] [Top] [Contents] [Index]
RootCause
RootCause performs root cause analysis of problems at the user's site, in the production system. This chapter discusses how to run traces on a remote computer.
RootCause has two components: the RootCause Console and the RootCause Agent. The Agent is the subset of RootCause that is used to run RootCause traces on a remote computer. The Console is the full product that allows one to define and view traces as well as run them (that is, the Console also includes the Agent).
If you're just "trying out" the deploy process on a single computer, your Console installation can also serve as the remote installation. If you really are deploying RootCause to a remote site you will want to install just the RootCause Agent subset there, and enable remote execution using RootCause agent licenses.
Follow the installation directions in "RootCause Agent Installation" to install the RootCause Agent on the remote computer; this only needs to be done once per remote computer.
After this is installed on the remote computer, you deploy RootCause trace definitions to the remote RootCause Agent and get back files that contain the logged trace data.
The Agent installation does not have its own license--the license is delivered with the deployed probes. Instead, you will obtain one or more agent license keys from OC Systems and append them to the file
$APROBE/licenses/agent_license.dat
in your RootCause Console installation. Agent licenses will be automatically copied into the deployed workspace (see "Deploying A RootCause Workspace"). See "Licensing" for a more in-depth discussion on licensing issues.
Any Java application is traceable with RootCause so long as it's running under a supported JRE. See "System Requirements", and "Your Application and Different JREs"
When you have built and tested the traces and probes, and you want to apply them to an application that exists at (or will be shipped to) a remote site, you are ready to deploy the workspace containing those traces and probes. This workspace will be your "flight recorder" for the application at the remote site. To generate the deploy (.dply) file:
Confirm that you're developing and testing with the same build of the application you'll be shipping. See "Building a "Traceable" Application".
Develop and test your traces locally. When you see the information you think you'll need at the remote site, then you're ready to deploy.
Enable the verify predefined UAL in the Workspace Browser window. This checks the correspondence between the program and modules on the remote system with those in the local (formatting) environment, and alerts the user when an incompatibility is detected.
Click on the Deploy button in the main Workspace Browser window. This will display the Deploy Dialog.
In the Deploy Dialog, enter a file name for your deploy file. This file will be created by RootCause, and it will contain the trace definitions for your current workspace.
In the Deploy window, click "OK". RootCause will attempt to create the dply file. For example, if you're using the workspace created in Chapter 5, "RootCause Demo", then this will create dply.
The .dply file will also contain the license needed to run RootCause on the remote computer. When the .dply file is created, the file$APROBE/licenses/agent_license.dat mentioned in
see "Installing The RootCause Agent" is automatically included. If the license file is not found, or does not contain a license, an error dialog will appear. If you see this, you can click "Yes" to proceed with deploying, or "No" if you wish to investigate getting a valid Agent license.
Transfer the .dply file over to the remote computer (be sure to specify binary mode if you use ftp).
On the remote computer open an xterm or other command shell.
Register the application on the remote computer using the rootcause register command. For example:
rootcause register Pi.dplyThis creates a workspace in the current directory (or a path specified with the -w option) and registers the workspace with the main Java class.
Enable RootCause on the remote computer in the environment where the application will be run, using the rootcause_on command. Note that this needs to be done in a parent process of the shell that will run the application(s) so that the application(s) will inherit the value of the environment variables it sets.
Run the application(s) as you normally would.
When you want to collect and examine the RootCause trace data, execute the rootcause collect command on the remote computer. For example:
Many classes may be collected at once by listing them on the collect command line. The applicable files in each registered workspace will be compressed into a single .clct file.
Transfer the .clct file back to the local computer where the RootCause Console is installed (be sure to specify binary mode if you use ftp).
In the RootCause GUI, click on the Decollect button in the main window. This will display the Decollect Data Dialog. If the RootCause GUI is not currently running, you may open the collect file when starting the GUI, for example:
rootcause open file.clct
In the Decollect Data Dialog, enter the name of the .clct file and the destination directory into which the file will be expanded. The destination directory should be empty as the decollect operation will expand a number of files into this directory. Then click "OK".
This will create a decollection, a directory, with suffix .dclct, containing the workspaces collected from the remote computer. It will then proceed with the Open Decollection operation, which will show a Trace Index Dialog for the newest data in the decollection.
Select the event(s) you wish to view, or use Select Data Files to change the data that was indexed.
Format the data into a Trace Display. If you used the verify predefined UAL as suggested in "Deploying A RootCause Workspace", you'll see a TEXT node identifying any mismatches that may cause formatting problems.
From the Trace Display for the decollected data, you can use Add Data Files To Display to add in the Decollected RootCause Log file and other data.