RCUG RootCause Files and Environment Variables
RootCause User Guide
Contents
- 1 RootCause Files and Environment Variables
- 1.1 Workspace
- 1.2 UAL File
- 1.3 Data (APD) File
- 1.4 Process Data Set
- 1.5 Deploy File
- 1.6 Collect File
- 1.7 Decollection
- 1.8 RootCause Registry
- 1.9 RootCause Log
- 1.10 .rootcause Directory
- 1.11 rootcause.properties
- 1.12 setup Script
- 1.13 Environment Variables
- 1.13.1 APROBE
- 1.13.2 APROBE_HOME
- 1.13.3 APROBE_JRE
- 1.13.4 APROBE_JRE
- 1.13.5 APROBE_JAVA_HEAPSIZE
- 1.13.6 APROBE_LOG
- 1.13.7 APROBE_REGISTRY
- 1.13.8 APROBE_SEARCH_PATH
- 1.13.9 LD_AUDIT (Solaris)
- 1.13.10 LD_PRELOAD (Linux)
- 1.13.11 AP_ROOTCAUSE_ENABLED (AIX)
- 1.13.12 RC_WORKSPACE_LOC
- 1.13.13 RC_SHORT_WORKSPACE_LOC
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.
<A NAME=HEADING10-2></A> <A NAME="UID-07environment_rc.fm-949847"></A>
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.
<A NAME=HEADING10-5></A> <A NAME="UID-07environment_rc.fm-949853"></A>
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.
<A NAME=HEADING10-7></A> <A NAME="UID-07environment_rc.fm-950024"></A>
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>
<A NAME=HEADING10-9></A> <A NAME="UID-07environment_rc.fm-950058"></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.
<A NAME=HEADING10-11></A> <A NAME="UID-07environment_rc.fm-949859"></A>
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.
<A NAME=HEADING10-13></A> <A NAME="UID-07environment_rc.fm-949861"></A>
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.
<A NAME=HEADING10-15></A> <A NAME="UID-07environment_rc.fm-949836"></A>
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>.
<A NAME=HEADING10-17></A> <A NAME="UID-07environment_rc.fm-949411"></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!
<A NAME=HEADING10-25></A> <A NAME="UID-07environment_rc.fm-949420"></A>
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.
<A NAME=HEADING10-33></A> <A NAME="UID-07environment_rc.fm-950674"></A>
.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.
<A NAME=HEADING10-44></A> <A NAME="UID-07environment_rc.fm-952716"></A>
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>.
<A NAME=HEADING10-48></A> <A NAME="UID-07environment_rc.fm-964274"></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.
<A NAME=HEADING10-50></A> <A NAME="UID-07environment_rc.fm-958874"></A>
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
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>.
<A NAME="LINK-07environment_rc.fm-lastpage"></A>
Copyright 2006-2017 OC Systems, Inc.