Difference between revisions of "RCUG 4 Getting Started"
m |
m |
||
Line 41: | Line 41: | ||
<!-- <DIV ID=MARKER-2-512></DIV> --> | <!-- <DIV ID=MARKER-2-512></DIV> --> | ||
setup script in your shell every time you log in or otherwise reinitialize your environment. Therefore it is a good idea to put the appropriate command above in your <code>~/.profile</code> (for Korn or Bourne shells) or <code>~/.login file</code> (for C shell). See | setup script in your shell every time you log in or otherwise reinitialize your environment. Therefore it is a good idea to put the appropriate command above in your <code>~/.profile</code> (for Korn or Bourne shells) or <code>~/.login file</code> (for C shell). See | ||
− | [["rcc-12.html#MARKER-9-2009">"RootCause and Different Shells"</DIV> | + | [[RCUG_RootCause_Command_Reference#RootCause_and_Different_Shells|"RootCause and Different Shells"]] |
− | for information about other shells. | + | <!-- [["rcc-12.html#MARKER-9-2009">"RootCause and Different Shells"</DIV> --> |
+ | for information about other shells. | ||
This script defines the <code>APROBE</code> environment variable and appends | This script defines the <code>APROBE</code> environment variable and appends | ||
Line 78: | Line 79: | ||
<OL> | <OL> | ||
− | <LI | + | <LI>Run your application in the normal way, but with RootCause enabled in its environment, for example: |
<DIV ID=MARKER-2-516></DIV>rootcause<DIV ID=MARKER-10-517></DIV>_on | <DIV ID=MARKER-2-516></DIV>rootcause<DIV ID=MARKER-10-517></DIV>_on | ||
<BR>my_app_driver arg1 arg2 | <BR>my_app_driver arg1 arg2 | ||
Line 84: | Line 85: | ||
<DIV ID=MARKER-2-519></DIV>rootcause<DIV ID=MARKER-10-520></DIV>_off | <DIV ID=MARKER-2-519></DIV>rootcause<DIV ID=MARKER-10-520></DIV>_off | ||
− | + | This will record information about the application in the | |
− | [["rcc-10.html#MARKER-9-963">RootCause Log</DIV> file. | + | [[RCUG_RootCause_Files_and_Environment_Variables#RootCause_Log|RootCause Log]] |
+ | [["rcc-10.html#MARKER-9-963">RootCause Log</DIV> file. | ||
− | + | NOTE: On AIX, you must use "apaudit my_app_driver" in the above command instead of just "my_app_driver" to allow RootCause to log and trace your application. See | |
[["#MARKER-9-532">Enabling RootCause for an AIX Application</DIV> | [["#MARKER-9-532">Enabling RootCause for an AIX Application</DIV> | ||
− | below. | + | below. |
− | <LI | + | <LI>Start the RootCause Console GUI with the |
<DIV ID=MARKER-2-521></DIV> | <DIV ID=MARKER-2-521></DIV> | ||
− | <code>[["rcc-12.html#MARKER-9-2101">rootcause open</DIV></CODE> | + | <code>[[RCUG_RootCause_Command_Reference#rootcause_open|rootcause open]]</code> |
+ | <!-- <code>[["rcc-12.html#MARKER-9-2101">rootcause open</DIV></CODE> --> | ||
command. This will open the | command. This will open the | ||
− | [["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> | + | [[RCUG_RootCause_GUI_Reference#Workspace_Browser|Workspace Browser]] |
+ | <!-- [["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> --> | ||
and the | and the | ||
− | [["rcc-11.html#MARKER-9-1725">Trace Display</DIV> | + | [[RCUG_RootCause_GUI_Reference#Trace_Display|Trace Display]] |
+ | <!-- [["rcc-11.html#MARKER-9-1725">Trace Display</DIV> --> | ||
showing the contents of the | showing the contents of the | ||
<DIV ID=MARKER-2-522></DIV> | <DIV ID=MARKER-2-522></DIV> | ||
− | RootCause log file. | + | RootCause log file. |
− | <LI | + | <LI>Use |
<EM> | <EM> | ||
<DIV ID=MARKER-2-523></DIV> | <DIV ID=MARKER-2-523></DIV> | ||
− | [["rcc-11.html#MARKER-9-1730">Open Associated Workspace</DIV> | + | [[RCUG_RootCause_GUI_Reference#Open_Associated_Workspace|Open Associated Workspace]] |
+ | <!-- [["rcc-11.html#MARKER-9-1730">Open Associated Workspace</DIV> --> | ||
</EM> | </EM> | ||
− | on the application program listed in the RootCause log display, and approve the creation of the new workspace. | + | on the application program listed in the RootCause log display, and approve the creation of the new workspace. |
− | <LI | + | <LI>Click |
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Setup|Setup]] |
− | [["rcc-11.html#MARKER-9-1426">Setup</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1426">Setup</DIV> --> |
</EM> | </EM> | ||
and define the probes for the application by choosing what you want to trace in the | and define the probes for the application by choosing what you want to trace in the | ||
<DIV ID=MARKER-2-524></DIV> | <DIV ID=MARKER-2-524></DIV> | ||
− | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV>. | + | [[RCUG_RootCause_GUI_Reference#Trace_Setup_Dialog|Trace Setup Dialog]]. |
− | Note that RootCause writes the probes to separate files, so the application itself remains totally unmodified. | + | <!-- [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV>. --> |
+ | Note that RootCause writes the probes to separate files, so the application itself remains totally unmodified. | ||
− | <LI | + | <LI>Execute the application as you normally would, but with rootcause "on", as in step 1 above. The application need not be executed from the RootCause GUI, although there is a convenience |
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Run|Run]] |
− | [["rcc-11.html#MARKER-9-1428">Run</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1428">Run</DIV> --> |
</EM> | </EM> | ||
− | button to do so. This makes it very simple to use RootCause, even if the application is deeply embedded in a complex system. | + | button to do so. This makes it very simple to use RootCause, even if the application is deeply embedded in a complex system. |
− | <LI | + | <LI>Click the |
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Run|Run]] |
− | [["rcc-11.html#MARKER-9-1431">Index</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1431">Index</DIV> --> |
</EM> | </EM> | ||
button to bring up the index of data that was logged for the newest process in the workspace, and double-click on an item there to format the trace data collected by the probes, or you can use the | button to bring up the index of data that was logged for the newest process in the workspace, and double-click on an item there to format the trace data collected by the probes, or you can use the | ||
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Examine|Examine]] |
− | [["rcc-11.html#MARKER-9-1432">Examine</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1432">Examine</DIV> --> |
</EM> | </EM> | ||
− | button to directly select the data file(s) you wish to view. | + | button to directly select the data file(s) you wish to view. |
− | <LI | + | <LI>In the |
− | [["rcc-11.html#MARKER-9-1725">Trace Display</DIV> | + | [[RCUG_RootCause_GUI_Reference#Trace_Display|Trace Display]] |
− | window that appears is a call tree. Here you can: | + | <!-- [["rcc-11.html#MARKER-9-1725">Trace Display</DIV> --> |
+ | window that appears is a call tree. Here you can: | ||
<UL> | <UL> | ||
− | <LI | + | <LI>Use the |
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Find|Find]] |
− | [["rcc-11.html#MARKER-9-1795">Find</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1795">Find</DIV> --> |
</EM> | </EM> | ||
− | button to search for specific functions or events in the data. | + | button to search for specific functions or events in the data. |
− | <LI | + | <LI>Select a node in the event tree and right-click to bring up the |
− | <EM> | + | <EM>[[RCUG_RootCause_GUI_Reference#Trace_Display_Popup_Menu|Trace Display Popup Menu]] |
− | [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> --> |
</EM>, | </EM>, | ||
− | from which you can disable traces and perform other operations. | + | from which you can disable traces and perform other operations. |
− | <LI | + | <LI>Select a |
<DIV ID=MARKER-2-525></DIV> | <DIV ID=MARKER-2-525></DIV> | ||
SYN_ | SYN_ | ||
<DIV ID=MARKER-10-526></DIV> | <DIV ID=MARKER-10-526></DIV> | ||
CALL_COUNTS node and use | CALL_COUNTS node and use | ||
− | [["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV> | + | [[RCUG_RootCause_GUI_Reference#Show_Associated_Table|Show Associated Table]] |
+ | <!-- [["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV> --> | ||
to view and navigate to the function | to view and navigate to the function | ||
<DIV ID=MARKER-10-527></DIV>s | <DIV ID=MARKER-10-527></DIV>s | ||
− | in the data file(s). | + | in the data file(s). |
− | <LI | + | <LI>Select a |
<DIV ID=MARKER-2-528></DIV> | <DIV ID=MARKER-2-528></DIV> | ||
LOAD_SHED | LOAD_SHED | ||
<DIV ID=MARKER-2-529></DIV> | <DIV ID=MARKER-2-529></DIV> | ||
<DIV ID=MARKER-10-530></DIV> | <DIV ID=MARKER-10-530></DIV> | ||
− | node and use | + | node and use [[RCUG_RootCause_GUI_Reference#Show_Associated_Table|Show Associated Table]] |
− | [["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV> | + | <!-- [["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV> --> |
to view the table of all function | to view the table of all function | ||
<DIV ID=MARKER-10-531></DIV>s | <DIV ID=MARKER-10-531></DIV>s | ||
for which tracing was disabled due to | for which tracing was disabled due to | ||
− | [["rcc-6.html#MARKER-9-433">load shedding</DIV> | + | [[RCUG_3_Terminology_and_Concepts#load_shedding|load shedding]] |
− | during the run, and disable the tracing of these during subsequent runs. | + | <!-- [["rcc-6.html#MARKER-9-433">load shedding</DIV> --> |
+ | during the run, and disable the tracing of these during subsequent runs. | ||
− | <LI | + | <LI>Save the output as <code>Text</code> or <code>XML</code> for off-line processing |
</UL> | </UL> | ||
− | <LI | + | <LI>When you have completed analyzing the data and modifying the trace to tune the information collected, go back to step 4 to trace parameters or add probe actions, or return to step 2 to choose another program to trace. |
</OL> | </OL> | ||
If you wish to run the probes on a remote computer, then there are additional steps to send a RootCause workspace to the remote computer before execution. These are discussed in detail in | If you wish to run the probes on a remote computer, then there are additional steps to send a RootCause workspace to the remote computer before execution. These are discussed in detail in | ||
− | [][["rcc-9.html#MARKER-9-873">Chapter 6, "Deploying the RootCause Workspace"</DIV>. | + | [[RCUG_6_Deploying_The_RootCause_Workspace|CHAPTER 6 - "Deploying the RootCause Workspace"]]. |
+ | <!-- [][["rcc-9.html#MARKER-9-873">Chapter 6, "Deploying the RootCause Workspace"</DIV>. --> | ||
This process is explored using a concrete example in the next chapter, | This process is explored using a concrete example in the next chapter, | ||
− | [][["rcc-8.html#MARKER-9-707">"RootCause Demo"</DIV>. | + | [[RCUG_5_RootCause_Demo|"RootCause Demo"]]. |
+ | <!-- [][["rcc-8.html#MARKER-9-707">"RootCause Demo"</DIV>. --> | ||
<!-- | <!-- | ||
Line 213: | Line 225: | ||
If it is not possible to directly invoke the application's executable from the command-line, you can simply rename the | If it is not possible to directly invoke the application's executable from the command-line, you can simply rename the | ||
− | [["rcc-6.html#MARKER-9-425">executable</DIV> | + | [[RCUG_3_Terminology_and_Concepts#executable|executable]] |
+ | <!-- [["rcc-6.html#MARKER-9-425">executable</DIV> --> | ||
to have a <CODE>.exe</CODE> suffix, and replace it with a (soft-link to a) script which will invoke the real application. For example: | to have a <CODE>.exe</CODE> suffix, and replace it with a (soft-link to a) script which will invoke the real application. For example: | ||
Line 226: | Line 239: | ||
script simply re-invokes the program with apaudit as in the second example above. | script simply re-invokes the program with apaudit as in the second example above. | ||
− | When we use the phrase | + | When we use the phrase "[[RCUG_3_Terminology_and_Concepts#run_with_rootcause_on|run with rootcause on]]" |
− | "[["rcc-6.html#MARKER-9-458">run with rootcause on</DIV>" | + | <!-- "[["rcc-6.html#MARKER-9-458">run with rootcause on</DIV>" --> |
we refer to any of the above mechanisms. | we refer to any of the above mechanisms. | ||
Revision as of 00:54, 9 October 2017
RootCause User Guide
Contents
Getting Started
rcc-7
-->
The Setup Script
Installation of RootCause from CD-ROM or compressed file is covered in Chapter 2, "Installing RootCause".
setup script in your shell every time you log in or otherwise reinitialize your environment. Therefore it is a good idea to put the appropriate command above in your ~/.profile
(for Korn or Bourne shells) or ~/.login file
(for C shell). See
"RootCause and Different Shells"
for information about other shells.
This script defines the APROBE
environment variable and appends
$APROBE/bin
to your
PATH environment variable. It also sets defaults for both
APROBE_REGISTRY and
APROBE_LOG environment variables. If the registry does not exist, the setup script will create a default one.
The setup script also defines aliases that are not inherited by subsequent non-login shells you may open, such as with the xterm
command. To ensure that these aliases are defined (specifically rootcause_on
and rootcause_off
), you may add the command:
. $APROBE/setup.kshrc
into your ~/.kshrc
file if you are using Korn shell, or the command
source $APROBE/setup.cshrc
into your ~/.cshrc
file if you are using C shell.
Now you're ready to run RootCause.
The RootCause Process
Using RootCause is typically an iterative process with the following pattern:
- Run your application in the normal way, but with RootCause enabled in its environment, for example:
rootcause_on
my_app_driver arg1 arg2
rootcause_offThis will record information about the application in the RootCause Log
[["rcc-10.html#MARKER-9-963">RootCause Log file.NOTE: On AIX, you must use "apaudit my_app_driver" in the above command instead of just "my_app_driver" to allow RootCause to log and trace your application. See
[["#MARKER-9-532">Enabling RootCause for an AIX Applicationbelow.
- Start the RootCause Console GUI with the
rootcause open
command. This will open the Workspace Browser and the Trace Display showing the contents of theRootCause log file.
- Use
Open Associated Workspace on the application program listed in the RootCause log display, and approve the creation of the new workspace.
- Click
Setup
and define the probes for the application by choosing what you want to trace in the
Trace Setup Dialog. Note that RootCause writes the probes to separate files, so the application itself remains totally unmodified.
- Execute the application as you normally would, but with rootcause "on", as in step 1 above. The application need not be executed from the RootCause GUI, although there is a convenience Run button to do so. This makes it very simple to use RootCause, even if the application is deeply embedded in a complex system.
- Click the Run button to bring up the index of data that was logged for the newest process in the workspace, and double-click on an item there to format the trace data collected by the probes, or you can use the Examine button to directly select the data file(s) you wish to view.
- In the
Trace Display
window that appears is a call tree. Here you can:
- Use the Find button to search for specific functions or events in the data.
- Select a node in the event tree and right-click to bring up the Trace Display Popup Menu , from which you can disable traces and perform other operations.
- Select a
SYN_
CALL_COUNTS node and use Show Associated Table to view and navigate to the function
sin the data file(s).
- Select a
LOAD_SHED
node and use Show Associated Table to view the table of all function
sfor which tracing was disabled due to load shedding during the run, and disable the tracing of these during subsequent runs.
- Save the output as
Text
orXML
for off-line processing
- When you have completed analyzing the data and modifying the trace to tune the information collected, go back to step 4 to trace parameters or add probe actions, or return to step 2 to choose another program to trace.
If you wish to run the probes on a remote computer, then there are additional steps to send a RootCause workspace to the remote computer before execution. These are discussed in detail in CHAPTER 6 - "Deploying the RootCause Workspace".
This process is explored using a concrete example in the next chapter, "RootCause Demo".
Enabling RootCause for an AIX Application
AIX provides no mechanism to cause a shared library to be automatically loaded into every application started. Therefore, the user must explicitly identify applications that are to be "intercepted" and recorded in the RootCause log, and subsequently traced using the process described in this document.
To run an executable under RootCause from the command line:
$ rootcause run my_program -opt arg2
or
$ rootcause on $ apaudit my_program -opt arg2 $ rootcause off
If it is not possible to directly invoke the application's executable from the command-line, you can simply rename the
executable
to have a .exe
suffix, and replace it with a (soft-link to a) script which will invoke the real application. For example:
$ mv my_program my_program.exe $ ln -s $APROBE/bin/run_with_apaudit my_program
The
run_with_apaudit
script simply re-invokes the program with apaudit as in the second example above.
When we use the phrase "run with rootcause on" we refer to any of the above mechanisms.
To enable automatic RootCause actions for Java applications (i.e., those normally run with the "java" command), you must do this for the native java executable
. This is generally not necessary, since you can more easily change "java" to "apaudit java" at the point of invocation. However, if you want to enable RootCause in your central Java installation, you should contact OC Systems for assistance: different Java versions are configured differently.
Copyright 2006-2017 OC Systems, Inc.