RCUG RootCause Files and Environment Variables

Next Previous Index Top

RootCause User Guide

RootCause Files and Environment Variables

---

     RCUG RootCause Files and Environment Variables

rcc-10

---

RootCause consists of a GUI to define traces, the Aprobe runtime to implement those traces, and a number of directories, files, and variables in the execution environment which control and record when the traces are applied. This chapter briefly describes those files and environment variables.

Workspace

All activity is performed in the context of a workspace. A workspace is a directory which contains all the information about the target program configuration, the configuration of the trace setup, and the resulting log files.

The contents of the workspace are manipulated by the RootCause GUI. If you change something within the workspace, such as a script or configuration file, the changes may be lost the next time a rootcause GUI operation is performed.

UAL File

A user action library (UAL) consists of a set of probes that are attached to the target program when it runs. The probes are activated when specified portions of the target program are reached. Some predefined UALs may be selected in the RootCause GUI Workspace Tree, additional ones are provided in the underlying Aprobe product, and the user can build custom UALs. As a user of RootCause, you do not need to be concerned with these files. RootCause handles them automatically. If you do use the underlying power of Aprobe, then you can create your own probes and your own UAL files.

Data (APD) File

Aprobe places the logged data from a traced executable into a Data File, also called an APD file. For the most part, RootCause users are isolated from this; however, when formatting the data, you can choose the data files you wish to view or generate an index from. See "Bounding Total Data" for more information.

Process Data Set

Process Data Sets are used to collect more than one wrap-around set (or ring) of data files for a single program. See "Data for Multiple Processes" for more information.

Deploy File

A deploy file (with extension .dply) is created by the Deploy operation in the RootCause GUI. It contains all the information needed by RootCause to trace a (possibly stripped) program at a remote site. The deploy file is transmitted to the remote computer and installed there to enable tracing of the program on the remote computer.

Collect File

A collect file (extension .clct) is created by the rootcause collect command. It contains all the information collected by RootCause for a traced program at a remote site. The collect file is transmitted from the remote computer to the local computer where it is "decollected" to examine its contents.

Decollection

The Decollect button in the RootCause GUI unpacks a .clct file created by the rootcause collect command. This creates a directory containing all the decollected workspaces. This directory is known as a Decollection (with extension .dclct), and is directly accessible using the Open Decollection and Recent Decollections items in the RootCause GUI's Workspace Menu.

RootCause Registry

To use RootCause on an application, you must first register the application by adding it to your RootCause registry. The RootCause GUI will do this automatically, and there is a command line interface as well (see the rootcause register command).

RootCause will only trace applications defined in the RootCause Registry.

On any one computer, there may be one or possibly many different registries, depending on your desired use. For example, it would be common for each user to have his/her own registry. Also, there may be one registry for the whole computer if it is a dedicated server and there is an integrated set of RootCause probes designed for that server.

The location of the RootCause registry is defined by the APROBE_REGISTRY environment variable, and is generally under the .rootcause Directory so that each user has a separate registry.

All manipulations of the registry are done using the rootcause register command, or via the items in the RootCause GUI's Workspace menu.

Important:

The registry is meant to be manipulated only with the rootcause register command (See "rootcause register"). Do not change its contents by any other means!

RootCause Log

The RootCause log file records what programs are started and what programs are traced while RootCause is enabled. Programs that are started but not traced are recorded as

APP_START events. Programs that are traced by RootCause are recorded as

APP_TRACED events. The RootCause log file may also contain other messages and debug information as

TEXT events. The RootCause log file may be examined in the GUI and used as a starting point for creating or opening the workspaces associated with programs recorded in the log file.

By default RootCause writes a line to the log file whenever an application is run with rootcause on, or fails to run due to an error. If you wish to record only those applications that are traced, you may change the verbosity level with the rootcause register command.

To log only applications that are registered and probed:

rootcause register -s verbose -e off

To log all applications that are executed when rootcause is enabled, whether or not they are registered:

rootcause register -s verbose -e on

While becoming familiar with RootCause, you may want to examine the log file often. You can display it using the rootcause log command.

.rootcause Directory

The directory

$HOME/.rootcause

is created and used by the RootCause GUI to maintain some user-specific attributes of your RootCause environment:

• the RootCause Log file is located here by default
• the RootCause Registry is located here by default as well.
• a customized rootcause.properties file may be placed here.
• a preferences file in this directory contains the recent workspaces and other RootCause GUI internal settings.
• temporary files are created here.

The directory is called .rootcause_linux on Linux and .rootcause_aix on AIX to avoid collisions and confusion on mixed systems sharing a common $HOME directory.

The APROBE_HOME may be used to specify a different location.

rootcause.properties

The file

$APROBE/lib/rootcause.properties 

defines some properties used to determine the RootCause appearance. In general, you need not be concerned with these, but if you wish to change the background color or other property defined by UIManager you can do so by placing an edited version of this file in the .rootcause Directory.

setup Script

The files $APROBE/setup and $APROBE/setup.csh are provided to define the RootCause environment in your shell. See Chapter 4, "The Setup Script" for details.

Environment Variables

APROBE

The APROBE environment variable points to the RootCause product installation directory, and is automatically defined by the setup script. We suggest that you do not modify this environment variable.

APROBE_HOME

The APROBE_HOME environment variable defines a non-default location for the .rootcause Directory.

If APROBE_HOME is defined when the $APROBE/setup or setup.csh script is run, the RootCause Log and RootCause Registry files are created under $APROBE_HOME. In this way, one can have a single system-wide RootCause environment by setting APROBE_HOME globally, and creating world-accessible registry and log files there.

APROBE_JRE

The APROBE_JRE environment variable specifies a non-default JRE (Java installation) to use instead of the one shipped with RootCause. See "Platform-Specific GUI Issues".

APROBE_JAVA_HEAPSIZE

The APROBE_JAVA_HEAPSIZE environment variable specifies a non-default Java heap sized to be use by the RootCause console GUI. The value of this environment variable is the entire Java parameter value. The default is "-Xmx128m".

APROBE_LOG

The APROBE_LOG environment variable specifies the location of the RootCause Log file (see "RootCause Log"). It is initialized by the setup script (see "The Setup Script") to the name rclog under the .rootcause Directory. If unset, the location $APROBE/arca/rc.log is used. Generally the RootCause Log and RootCause Registry are kept in the same directory, defined by the value of the APROBE_HOME environment variable, so you shouldn't have to set this directly.

APROBE_REGISTRY

The APROBE_REGISTRY environment variable specifies the location of the RootCause registry file (see "RootCause Registry"). It is initialized by the setup Script to the name registry under the .rootcause Directory. If unset, the location $APROBE/arca/registry is used. Generally the RootCause Log and RootCause Registry are kept in the same directory, defined by the value of the APROBE_HOME environment variable, so you shouldn't have to set this directly.

APROBE_SEARCH_PATH

The APROBE_SEARCH_PATH environment variable identifies directories to be searched by RootCause for source files when the file is not found in the directory from which it was compiled. If defined, The APROBE_SEARCH_PATH environment variable is a colon-separated list of directories (like PATH and LIBPATH) in which to search for a a source file to display, if the file is not found in the directory recorded in the

object file.

For example, if a program is compiled from files in directories /build/common, /build/console, and /build/gui, and the directory /build has been moved to /old/build, you could do:

export APROBE_SEARCH_PATH=\   
   "/old/build/common:/old/build/console:/old/build/gui" 

Use of the environment variable to find source files is not usually necessary, since the RootCause GUI provides an interface for specifying the search path the first time it's needed, and this path is recorded in the workspace.

The APROBE_SEARCH_PATH environment variable is also used by RootCause and Aprobe to find object files that have been moved -- see Appendix A of the Aprobe User's Guide.

LD_AUDIT (Solaris)

The LD_AUDIT environment variable is recognized by the Solaris operating system and is used by RootCause to hook into applications that are registered by RootCause. The commands rootcause_on and rootcause_off will set and unset the LD_AUDIT environment variable for RootCause.

The RootCause setup script does not set the LD_AUDIT environment variable, so you will need to execute rootcause_on after the setup script to actually cause RootCause to start examining each new process for probing. LD_AUDIT is a normal Solaris environment variable with the usual semantics about being inherited by sub-processes, etc.

At OC Systems, we have set LD_AUDIT at system boot time, so all processes will be examined by RootCause as they launch, to ensure its robustness and low overhead. But you can limit the scope of RootCause by limiting the scope of where the LD_AUDIT environment variable is set, even though the overhead imposed by this checking is small.

For Solaris 7 and higher, the LD_AUDIT_64 environment variable may also be set to point at a dummy 64-bit library so that the runtime linker does not issue warning messages. This library does not invoke RootCause because 64-bit applications are currently not supported.

Note that the LD_PRELOAD environment variable is not used by RootCause on Solaris.

LD_PRELOAD (Linux)

The LD_PRELOAD environment variable is recognized by the Linux operating system and is used by RootCause to hook into applications that are registered by RootCause. The commands rootcause_on and

rootcause_off will set and unset the LD_PRELOAD environment variable for RootCause.

The RootCause setup script does not set the LD_PRELOAD environment variable, so you will need to execute rootcause_on after the setup script to actually cause RootCause to start examining each new process for probing. LD_PRELOAD is a normal Linux environment variable with the usual semantics about being inherited by sub-processes, etc. You can limit the scope of RootCause by limiting the scope of where the LD_PRELOAD environment variable is set, even though the overhead imposed by this checking is small.

Note that LD_PRELOAD may be used by other tools or even your own application. In such cases you must take care in updating this variable: contact OC Systems for assistance in this case.

For Solaris 7 and higher, the LD_AUDIT_64 environment variable may also be set to point at a dummy 64-bit library so that the runtime linker does not issue warning messages. This library does not invoke RootCause because 64-bit applications are currently not supported.

AP_ROOTCAUSE_ENABLED (AIX)

AIX has no mechanism corresponding to LD_AUDIT or LD_PRELOAD that allows libraries to be specified at load time, and hence one cannot just set an environment variable to start intercepting processes on AIX. Instead, one identifies a program that one may want to intercept, renames the program executable, and replaces it with a script called

run_with_apaudit, as described in "Enabling RootCause for an AIX Application". This script recognizes the

AP_ROOTCAUSE_ENABLED environment variable, which is defined by the

rootcause_on alias and unset by the

rootcause_off alias.

RC_WORKSPACE_LOC

When an application is run with rootcause on and is registered with a workspace, the location of that workspace is defined in the environment variable RC_WORKSPACE_LOC prior to the application being run with aprobe. This allows one to use this environment variable to references files in aprobe options or within custom probes. This is especially useful in specifying the location of the configuration file needed by a user-defined UAL in the Aprobe Parameters field of the Add UAL Dialog. This environment variable is also defined when data is formatted, and so can be used in Apformat Parameters as well.

RC_SHORT_WORKSPACE_LOC

If the path to your workspace may contain blanks (such as is common on Windows platforms), you should use the RC_SHORT_WORKSPACE_LOC environment variable instead of the RC_WORKSPACE_LOC.

---

Copyright 2006-2017 OC Systems, Inc.

Next Previous Index Top