Revision as of 19:07, 24 September 2017

RootCause User Guide

RootCause Files and Environment Variables

     RCUG RootCause Files and Environment Variables

rcc-10

RootCause

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 <A NAME=MARKER-2-947></A> 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 ( []<A HREF="rcc-6.html#MARKER-9-479">UAL</A> ) 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 []<A HREF="rcc-6.html#MARKER-9-445">predefined UAL</A>s may be selected in the RootCause GUI []<A HREF="rcc-11.html#MARKER-9-1323">Workspace Tree</A>, 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 []<A HREF="rcc-6.html#MARKER-9-436">log</A> ged data from a traced []<A HREF="rcc-6.html#MARKER-9-425">executable</A> into a []<A HREF="rcc-6.html#MARKER-9-407">Data File</A>, also called an []<A HREF="rcc-6.html#MARKER-9-392">APD file</A>. 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

[]<A HREF="rcc-6.html#MARKER-9-370">"Bounding Total Data"</A> for more information. <A NAME=MARKER-10-951></A>

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 []<A HREF="rcc-6.html#MARKER-9-368">"Data for Multiple Processes"</A> for more information.

Deploy File

A []<A HREF="rcc-6.html#MARKER-9-418">deploy</A> file (with extension .dply) is created by the []<A HREF="rcc-11.html#MARKER-9-1429">Deploy</A> operation in the RootCause GUI. It contains all the information needed by RootCause

to trace a (possibly []<A HREF="rcc-6.html#MARKER-9-468">stripped</A> ) program at a []<A HREF="rcc-6.html#MARKER-9-456">remote</A> 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 []<A HREF="rcc-6.html#MARKER-9-404">collect</A> file (extension .clct) is created by the <A NAME=MARKER-2-953></A> []<A HREF="rcc-12.html#MARKER-9-2027">rootcause collect</A> command. It contains all the information collected by RootCause for a traced

program at a remote site. The <A NAME=MARKER-2-954></A> collect file is transmitted from the remote computer to the local computer where it

is " []<A HREF="rcc-6.html#MARKER-9-410">decollect</A>ed" to examine its contents.

Decollection

The []<A HREF="rcc-11.html#MARKER-9-1430">Decollect</A> button in the RootCause GUI unpacks a <A NAME=MARKER-2-955></A> .clct file created by the []<A HREF="rcc-12.html#MARKER-9-2027">rootcause collect</A> command. This creates a directory containing all the decollected workspaces. This

directory is known as a <A NAME=MARKER-2-956></A> Decollection (with extension .dclct), and is directly accessible using

the []<A HREF="rcc-11.html#MARKER-9-1370">Open Decollection</A> and []<A HREF="rcc-11.html#MARKER-9-1371">Recent Decollections</A> items in the RootCause GUI's []<A HREF="rcc-11.html#MARKER-9-1360">Workspace Menu</A>.

RootCause Registry

To use RootCause on an application, you must first []<A HREF="rcc-6.html#MARKER-9-451">register</A> the application by adding it to your <A NAME=MARKER-9-958></A> RootCause []<A HREF="rcc-6.html#MARKER-9-453">registry</A>. The RootCause GUI will do this automatically, and there is a command line interface

as well (see the <A NAME=MARKER-9-959></A> []<A HREF="rcc-12.html#MARKER-9-2107">rootcause register</A> command).

RootCause will only trace applications defined in the RootCause Registry.

<A NAME=MARKER-10-960></A> 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 <A NAME=MARKER-2-961></A> <A HREF="#MARKER-9-992">APROBE_REGISTRY</A> environment variable, and is generally under the <A HREF="#MARKER-9-971">.rootcause Directory</A> so that each user has a separate registry.

All manipulations of the registry are done using the <A NAME=MARKER-2-962></A> []<A HREF="rcc-12.html#MARKER-9-2107">rootcause register</A> 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 <A HREF="rcc-12.html#MARKER-9-2107">"rootcause register"</A> ). 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 <A NAME=MARKER-2-964></A> APP_START events. Programs that are traced by RootCause are recorded as <A NAME=MARKER-2-965></A> APP_TRACED events. The RootCause log file may also contain other messages and debug

information as <A NAME=MARKER-2-966></A> 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 <A NAME=MARKER-2-967></A> <A HREF="rcc-6.html#MARKER-9-458">run with rootcause on</A>, 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 <A HREF="rcc-12.html#MARKER-9-2107">rootcause register</A> command.

To log only applications that are registered and probed:

<A NAME=MARKER-2-968></A>
rootcause register -s verbose -e off

<A NAME=MARKER-10-969></A> To log all applications that are executed when rootcause is enabled, whether or not

they are registered:

rootcause register -s verbose -e on

<A NAME=MARKER-10-970></A> While becoming familiar with RootCause, you may want to examine the log file often.

You can display it using the

<A HREF="rcc-12.html#MARKER-9-2075">rootcause log</A> command.

.rootcause Directory

The directory

<A NAME=MARKER-10-972></A>
$HOME/.rootcause

is created and used by the RootCause GUI to maintain some user-specific attributes

of your RootCause environment:

the <A HREF="#MARKER-9-963">RootCause Log</A> file is located here by default
the <A HREF="#MARKER-9-957">RootCause Registry</A> is located here by default as well.
a customized <A HREF="#MARKER-9-975">rootcause.properties</A> file may be placed here.
a <A NAME=MARKER-2-973></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 <A NAME=MARKER-2-974></A> <A HREF="#MARKER-9-982">APROBE_HOME</A> may be used to specify a different location.

rootcause.properties

The file

<A NAME=MARKER-10-976></A>
<A NAME=MARKER-10-977></A>
$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 <A HREF="#MARKER-9-971">.rootcause Directory</A>.

setup Script

The files $APROBE/setup and $APROBE/setup.csh are

provided to define the RootCause environment in your shell. See []<A HREF="rcc-7.html#MARKER-9-509">Chapter 4, "The Setup Script"</A> for details.

Environment Variables

APROBE

The <A NAME=MARKER-2-980></A> APROBE environment variable points to the RootCause product installation directory,

and is <A NAME=MARKER-10-981></A> automatically defined by the setup script. We suggest that you do not modify this

environment variable.

APROBE_HOME

The <A NAME=MARKER-2-983></A> APROBE_HOME environment variable defines a non-default location for the <A HREF="#MARKER-9-971">.rootcause Directory</A>.

If APROBE_HOME is defined when the $APROBE/setup or setup.csh script is run, the <A HREF="#MARKER-9-963">RootCause Log</A> and <A HREF="#MARKER-9-957">RootCause Registry</A> 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 <A NAME=MARKER-2-984></A> <A NAME=MARKER-2-985></A> APROBE_JRE environment variable specifies a non-default <A HREF="rcc-6.html#MARKER-9-431">JRE</A> (Java installation) to use instead of the one shipped with RootCause. See []<A HREF="rcc-11.html#MARKER-9-1871">"Platform-Specific GUI Issues"</A>.

APROBE_JAVA_HEAPSIZE

The <A NAME=MARKER-2-986></A> <A NAME=MARKER-2-987></A> 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 <A NAME=MARKER-2-988></A> <A NAME=MARKER-2-989></A> APROBE_LOG environment variable specifies the location of the RootCause Log file

(see []<A HREF="#MARKER-9-963">"RootCause Log"</A> ). It is initialized by the setup script (see <A HREF="rcc-7.html#MARKER-9-509">"The Setup Script"</A> ) to the name <A NAME=MARKER-2-990></A> rclog under the <A HREF="#MARKER-9-971">.rootcause Directory</A>. If unset, the location $APROBE/arca/rc.log is used. Generally the <A HREF="#MARKER-9-963">RootCause Log</A> and <A HREF="#MARKER-9-957">RootCause Registry</A> are kept in the same directory, defined by the value of the <A HREF="#MARKER-9-982">APROBE_HOME</A> environment variable, so you shouldn't have to set this directly. <A NAME=MARKER-10-991></A>

APROBE_REGISTRY

The <A NAME=MARKER-2-993></A> <A NAME=MARKER-2-994></A> APROBE_REGISTRY environment variable specifies the location of the RootCause

registry file (see <A HREF="#MARKER-9-957">"RootCause Registry"</A> ). It is initialized by the <A HREF="#MARKER-9-978">setup Script</A> to the name registry under the <A HREF="#MARKER-9-971">.rootcause Directory</A>. If unset, the location $APROBE/arca/registry is used. Generally the <A HREF="#MARKER-9-963">RootCause Log</A> and <A HREF="#MARKER-9-957">RootCause Registry</A> are kept in the same directory, defined by the value of the <A HREF="#MARKER-9-982">APROBE_HOME</A> environment variable, so you shouldn't have to set this directly.

APROBE_SEARCH_PATH

The <A NAME=MARKER-2-995></A> <A NAME=MARKER-2-996></A> 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 <A NAME=MARKER-10-997></A> object file.

For example, if a program <A NAME=MARKER-10-998></A> 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"

<A NAME=MARKER-10-999></A> Use of the environment variable to find source files is not usually necessary,

since the RootCause GUI provides an interface for specifying the <A NAME=MARKER-2-1000></A> search path the first time it's needed, and this path is recorded in the workspace.

The <A NAME=MARKER-2-1001></A> 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 <A NAME=MARKER-2-1002></A> <A NAME=MARKER-2-1003></A> LD_AUDIT environment variable is recognized by the <A NAME=MARKER-2-1004></A> Solaris operating system and is used by RootCause to hook into applications

that are registered by RootCause. The commands <A NAME=MARKER-2-1005></A> rootcause_on and <A NAME=MARKER-2-1006></A> 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 <A NAME=MARKER-2-1007></A> <A NAME=MARKER-2-1008></A> LD_PRELOAD environment variable is recognized by the <A NAME=MARKER-2-1009></A> Linux operating system and is used by RootCause to hook into applications

that are registered by RootCause. The commands rootcause_on and <A

NAME=MARKER-2-1010></A> 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 <A NAME=MARKER-2-1011></A> 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)

<A NAME=MARKER-2-1012></A> 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 <A NAME=MARKER-2-1013></A> run_with_apaudit, as described in <A HREF="rcc-7.html#MARKER-9-532">"Enabling RootCause for an AIX

Application"</A>. This script recognizes the <A NAME=MARKER-2-1014></A> AP_ROOTCAUSE_ENABLED environment variable, which is defined by the <A NAME=MARKER-2-1015></A> rootcause_on alias and unset by the <A NAME=MARKER-2-1016></A> rootcause_off alias.

RC_WORKSPACE_LOC

When an application is <A HREF="rcc-6.html#MARKER-9-458">run with rootcause on</A> and is <A HREF="rcc-6.html#MARKER-9-451">register</A>ed with a <A HREF="rcc-6.html#MARKER-9-482">workspace</A>, the location of that workspace is defined in the environment variable <A NAME=MARKER-2-1018></A> RC_WORKSPACE_LOC prior to the application being run with <A NAME=MARKER-2-1019></A> 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 <A HREF="rcc-11.html#MARKER-9-1457">Aprobe Parameters</A> field of the <A HREF="rcc-11.html#MARKER-9-1444">Add UAL Dialog</A>. This environment variable is also defined when data is formatted, and so can be

used in <A HREF="rcc-11.html#MARKER-9-1461">Apformat Parameters</A> 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 <A NAME=MARKER-2-1021></A> RC_SHORT_WORKSPACE_LOC environment variable instead of the <A HREF="#MARKER-9-1017">RC_WORKSPACE_LOC</A>.

Next Previous Index Top

Navigation menu

Difference between revisions of "RCUG RootCause Files and Environment Variables"

Revision as of 19:07, 24 September 2017

Contents

RootCause Files and Environment Variables

Workspace

UAL File

Data (APD) File

Process Data Set

Deploy File

Collect File

Decollection

RootCause Registry

Important:

RootCause Log

.rootcause Directory

rootcause.properties

setup Script

Environment Variables

APROBE

APROBE_HOME

APROBE_JRE

APROBE_JRE

APROBE_JAVA_HEAPSIZE

APROBE_LOG

APROBE_REGISTRY

APROBE_SEARCH_PATH

LD_AUDIT (Solaris)

LD_PRELOAD (Linux)

AP_ROOTCAUSE_ENABLED (AIX)

RC_WORKSPACE_LOC

RC_SHORT_WORKSPACE_LOC

@@ Line 40: / Line 40: @@
 ----  <!--  <HR>  -->
-RootCause consists of a
+RootCause consists of a [[RCUG_3_Terminology_and_Concepts#MARKER-9-429|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 <A NAME=MARKER-2-947></A> environment variables.
-[]<A HREF="rcc-6.html#MARKER-9-429">GUI</A>
-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
-<A NAME=MARKER-2-947></A>
-environment variables.
 <A NAME=HEADING10-2></A>