Difference between revisions of "RCUG 5 RootCause Demo"
m |
m |
||
Line 38: | Line 38: | ||
Before running this RootCause Demo, you must install and set up to use RootCause as described in | Before running this RootCause Demo, you must install and set up to use RootCause as described in | ||
[["rcc-7.html#MARKER-9-508">Chapter 4, "Getting Started"</DIV> | [["rcc-7.html#MARKER-9-508">Chapter 4, "Getting Started"</DIV> | ||
− | [[]]. This will define the APROBE environment variable which is necessary to use RootCause. | + | [[RCUG_4_Getting_Started#MARKER-9-508|Chapter 4, "Getting Started"]]. This will define the APROBE environment variable which is necessary to use RootCause. |
In the instructions that follow, we'll use <CODE>$APROBE</CODE> to refer to the path where RootCause is installed, for example <CODE>/opt/aprobe.</CODE> | In the instructions that follow, we'll use <CODE>$APROBE</CODE> to refer to the path where RootCause is installed, for example <CODE>/opt/aprobe.</CODE> | ||
Line 53: | Line 53: | ||
Lastly, make sure your DISPLAY environment variable is set. If you're using a Windows client that is running X emulator software such as eXceed or Reflection, we recommend you move to a Unix display for your initial evaluation. If this is impractical, see | Lastly, make sure your DISPLAY environment variable is set. If you're using a Windows client that is running X emulator software such as eXceed or Reflection, we recommend you move to a Unix display for your initial evaluation. If this is impractical, see | ||
[["rcc-11.html#MARKER-9-1878">"X-emulators: (Exceed, Reflection)"</DIV> | [["rcc-11.html#MARKER-9-1878">"X-emulators: (Exceed, Reflection)"</DIV> | ||
− | [[]]. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]. |
<DIV ID=HEADING8-12></DIV> | <DIV ID=HEADING8-12></DIV> | ||
Line 72: | Line 72: | ||
The <CODE>rootcause_on</CODE> command enables the automatic logging of every process that is started, and <CODE>rootcause_off</CODE> disables this logging. When the pi_demo program is " | The <CODE>rootcause_on</CODE> command enables the automatic logging of every process that is started, and <CODE>rootcause_off</CODE> disables this logging. When the pi_demo program is " | ||
[["rcc-6.html#MARKER-9-451">register</DIV> | [["rcc-6.html#MARKER-9-451">register</DIV> | ||
− | [[]]ed" with RootCause, it will be traced according to your specifications as well as simply being logged. The illustration below shows the set up and demo execution.. | + | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]]ed" with RootCause, it will be traced according to your specifications as well as simply being logged. The illustration below shows the set up and demo execution.. |
<!-- <IMG ALIGN=TOP SRC="sol_cpp_run1.gif"> --> | <!-- <IMG ALIGN=TOP SRC="sol_cpp_run1.gif"> --> | ||
Line 80: | Line 80: | ||
NOTE: On AIX, the above process is slightly different than shown above. The invocation of the program must be done with the | NOTE: On AIX, the above process is slightly different than shown above. The invocation of the program must be done with the | ||
[["rcc-12.html#MARKER-9-2119">rootcause run</DIV> | [["rcc-12.html#MARKER-9-2119">rootcause run</DIV> | ||
− | [[]] command directly. For example, the above sequence is changed to: | + | [[RCUG_RootCause_Command_Reference|CHAPTER 9 - RootCause Command Reference]] command directly. For example, the above sequence is changed to: |
<PRE> | <PRE> | ||
rootcause run $APROBE/demo/RootCause/C++/pi_demo | rootcause run $APROBE/demo/RootCause/C++/pi_demo | ||
Line 88: | Line 88: | ||
See | See | ||
[["rcc-7.html#MARKER-9-532">"Enabling RootCause for an AIX Application"</DIV> | [["rcc-7.html#MARKER-9-532">"Enabling RootCause for an AIX Application"</DIV> | ||
− | [[]]. | + | [[RCUG_4_Getting_Started#MARKER-9-532|"Enabling RootCause for an AIX Application"]]. |
<DIV ID=HEADING8-20></DIV> | <DIV ID=HEADING8-20></DIV> | ||
Line 103: | Line 103: | ||
This will open the RootCause main window, and then a view of the RootCause log. This shows the <EM> | This will open the RootCause main window, and then a view of the RootCause log. This shows the <EM> | ||
[["rcc-11.html#MARKER-9-1725">Trace Display</DIV> | [["rcc-11.html#MARKER-9-1725">Trace Display</DIV> | ||
− | [[]]</EM> window, the window for viewing all trace events. On the left is the Event Tree; on the upper right is the source/text window; and on the lower right is the "details" window. In the text window you will see some information about the log file. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> window, the window for viewing all trace events. On the left is the Event Tree; on the upper right is the source/text window; and on the lower right is the "details" window. In the text window you will see some information about the log file. |
<DIV ID=MARKER-2-720></DIV> | <DIV ID=MARKER-2-720></DIV> | ||
Line 112: | Line 112: | ||
Locate the APP_START event (in the Trace Event window) associated with the <CODE>pi_demo</CODE> program run earlier. To view information about this event, select the APP_START node in the event tree with a left click. This will fill in "details" about that event in the lower right window.With the APP_START pi_demo node highlighted, right-click to bring up the | Locate the APP_START event (in the Trace Event window) associated with the <CODE>pi_demo</CODE> program run earlier. To view information about this event, select the APP_START node in the event tree with a left click. This will fill in "details" about that event in the lower right window.With the APP_START pi_demo node highlighted, right-click to bring up the | ||
[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | ||
− | [[]]. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]. |
<DIV ID=MARKER-10-725></DIV> | <DIV ID=MARKER-10-725></DIV> | ||
Click <EM> | Click <EM> | ||
[["rcc-11.html#MARKER-9-1730">Open Associated Workspace</DIV> | [["rcc-11.html#MARKER-9-1730">Open Associated Workspace</DIV> | ||
− | [[]]</EM> in the popup-menu of the pi_demo APP_START event. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> in the popup-menu of the pi_demo APP_START event. |
<DIV ID=MARKER-10-726></DIV> | <DIV ID=MARKER-10-726></DIV> | ||
Line 127: | Line 127: | ||
This will open a <EM> | This will open a <EM> | ||
[["rcc-11.html#MARKER-9-1434">New Workspace Dialog</DIV> | [["rcc-11.html#MARKER-9-1434">New Workspace Dialog</DIV> | ||
− | [[]]</EM> with the program name and default workspace filled in. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> with the program name and default workspace filled in. |
This combination: selecting a node in the tree, then using the popup menu to choose an operation, is the basic way of working within RootCause. | This combination: selecting a node in the tree, then using the popup menu to choose an operation, is the basic way of working within RootCause. | ||
Line 165: | Line 165: | ||
You now see the <EM>RootCause | You now see the <EM>RootCause | ||
[["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> | [["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> | ||
− | [[]]</EM>. This is described in detail in | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>. This is described in detail in |
[["rcc-11.html#MARKER-9-1320">Chapter 8, "RootCause GUI Reference"</DIV> | [["rcc-11.html#MARKER-9-1320">Chapter 8, "RootCause GUI Reference"</DIV> | ||
− | [[]]. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]. |
<DIV ID=MARKER-10-737></DIV> | <DIV ID=MARKER-10-737></DIV> | ||
Line 184: | Line 184: | ||
<LI>Predefined UALs selected from the | <LI>Predefined UALs selected from the | ||
[["rcc-11.html#MARKER-9-1323">Workspace Tree</DIV> | [["rcc-11.html#MARKER-9-1323">Workspace Tree</DIV> | ||
− | [[]]; | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]; |
<LI>Method and Line traces selected from the | <LI>Method and Line traces selected from the | ||
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | ||
− | [[]]; | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]; |
<LI>Probes to gather or preserve data, also selected in the | <LI>Probes to gather or preserve data, also selected in the | ||
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | ||
− | [[]]; and | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]; and |
<LI>User-written custom probes as described in | <LI>User-written custom probes as described in | ||
[["rcc-13.html#MARKER-9-2198">"Writing Custom Probes"</DIV> | [["rcc-13.html#MARKER-9-2198">"Writing Custom Probes"</DIV> | ||
− | [[]]. | + | [[RCUG_7_Selected_Topics|CHAPTER 10 - Selected Topics]]. |
</UL> | </UL> | ||
Line 211: | Line 211: | ||
Under the | Under the | ||
[["rcc-11.html#MARKER-9-1330">UALs node</DIV> | [["rcc-11.html#MARKER-9-1330">UALs node</DIV> | ||
− | [[]] in the | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] in the |
[["rcc-11.html#MARKER-9-1323">Workspace Tree</DIV> | [["rcc-11.html#MARKER-9-1323">Workspace Tree</DIV> | ||
− | [[]]: | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]: |
<DIV ID=MARKER-10-742></DIV> | <DIV ID=MARKER-10-742></DIV> | ||
Line 231: | Line 231: | ||
<LI>Click on the <EM> | <LI>Click on the <EM> | ||
[["rcc-11.html#MARKER-9-1426">Setup</DIV> | [["rcc-11.html#MARKER-9-1426">Setup</DIV> | ||
− | [[]]</EM> button in the button bar. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> button in the button bar. |
</OL> | </OL> | ||
Line 244: | Line 244: | ||
This will open the <EM> | This will open the <EM> | ||
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | ||
− | [[]]</EM>, showing the modules of the application in the <EM> | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>, showing the modules of the application in the <EM> |
[["rcc-11.html#MARKER-9-1533">Program Contents Tree</DIV> | [["rcc-11.html#MARKER-9-1533">Program Contents Tree</DIV> | ||
− | [[]]</EM>. The | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>. The |
[["rcc-11.html#MARKER-9-1533">Program Contents Tree</DIV> | [["rcc-11.html#MARKER-9-1533">Program Contents Tree</DIV> | ||
− | [[]] identifies the modules, files, functions, methods, and data in the program, and allows you to specify complex actions on each function and method. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] identifies the modules, files, functions, methods, and data in the program, and allows you to specify complex actions on each function and method. |
<DIV ID=MARKER-10-754></DIV> | <DIV ID=MARKER-10-754></DIV> | ||
Line 259: | Line 259: | ||
<LI>Click on the <CODE>pi_demo.cpp</CODE> source file node, then right-click to see the <EM> | <LI>Click on the <CODE>pi_demo.cpp</CODE> source file node, then right-click to see the <EM> | ||
[["rcc-11.html#MARKER-9-1545">Trace Setup Popup Menu</DIV> | [["rcc-11.html#MARKER-9-1545">Trace Setup Popup Menu</DIV> | ||
− | [[]]</EM>. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>. |
<DIV ID=MARKER-10-756></DIV> | <DIV ID=MARKER-10-756></DIV> | ||
<LI>Click <EM> | <LI>Click <EM> | ||
[["rcc-11.html#MARKER-9-1557">Trace All In</DIV> | [["rcc-11.html#MARKER-9-1557">Trace All In</DIV> | ||
− | [[]]</EM> pi_demo.cpp. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> pi_demo.cpp. |
<LI>Click the <EM>OK</EM> button at the bottom right of the dialog to record the trace and dismiss the Trace Setup dialog. | <LI>Click the <EM>OK</EM> button at the bottom right of the dialog to record the trace and dismiss the Trace Setup dialog. | ||
Line 301: | Line 301: | ||
This time, since the program is registered with a workspace, it will be traced as specified in the workspace, and the resulting output will be recorded within the workspace. There will be some startup delay, but if you notice that the program runs slower once started, this is probably because your workspace is being accessed across the network from your machine. See | This time, since the program is registered with a workspace, it will be traced as specified in the workspace, and the resulting output will be recorded within the workspace. There will be some startup delay, but if you notice that the program runs slower once started, this is probably because your workspace is being accessed across the network from your machine. See | ||
[["rcc-13.html#MARKER-9-2164">"RootCause and Efficiency Concerns"</DIV> | [["rcc-13.html#MARKER-9-2164">"RootCause and Efficiency Concerns"</DIV> | ||
− | [[]]. | + | [[RCUG_7_Selected_Topics|CHAPTER 10 - Selected Topics]]. |
<DIV ID=HEADING8-73></DIV> | <DIV ID=HEADING8-73></DIV> | ||
Line 310: | Line 310: | ||
We're now ready to view the data generated by running with our Trace. This is discussed in detail in | We're now ready to view the data generated by running with our Trace. This is discussed in detail in | ||
[["rcc-6.html#MARKER-9-366">"RootCause Data Management"</DIV> | [["rcc-6.html#MARKER-9-366">"RootCause Data Management"</DIV> | ||
− | [[]]. | + | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]]. |
In the | In the | ||
[["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> | [["rcc-11.html#MARKER-9-1321">Workspace Browser</DIV> | ||
− | [[]] window, do the following: | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] window, do the following: |
<OL> | <OL> | ||
<LI>Click the | <LI>Click the | ||
[["rcc-11.html#MARKER-9-1431">Index</DIV> | [["rcc-11.html#MARKER-9-1431">Index</DIV> | ||
− | [[]] button. This will bring up the <EM> | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] button. This will bring up the <EM> |
[["rcc-11.html#MARKER-9-1680">Trace Index Dialog</DIV> | [["rcc-11.html#MARKER-9-1680">Trace Index Dialog</DIV> | ||
− | [[]]</EM> for the most recently generated data. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> for the most recently generated data. |
<LI>In the Trace Index Dialog, click the | <LI>In the Trace Index Dialog, click the | ||
[["rcc-11.html#MARKER-9-1699">Select Events</DIV> | [["rcc-11.html#MARKER-9-1699">Select Events</DIV> | ||
− | [[]] button. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] button. |
<LI>In the | <LI>In the | ||
[["rcc-11.html#MARKER-9-1711">Select Events Dialog</DIV> | [["rcc-11.html#MARKER-9-1711">Select Events Dialog</DIV> | ||
− | [[]], check "Exceptions" to index exception events, then click | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]], check "Exceptions" to index exception events, then click |
[["rcc-11.html#MARKER-9-1718">Update</DIV> | [["rcc-11.html#MARKER-9-1718">Update</DIV> | ||
− | [[]] to close the dialog and refresh the Index. You should now see something like the dialog below: | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] to close the dialog and refresh the Index. You should now see something like the dialog below: |
</OL> | </OL> | ||
Line 371: | Line 371: | ||
You can see more information about the exception in the | You can see more information about the exception in the | ||
[["rcc-11.html#MARKER-9-1830">Event Details Pane</DIV> | [["rcc-11.html#MARKER-9-1830">Event Details Pane</DIV> | ||
− | [[]] in the lower right. | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] in the lower right. |
If you scroll to the top of the Event Trace, you should see three threads: one for the main thread, and one for each of the threads which is started to compute Pi. | If you scroll to the top of the Event Trace, you should see three threads: one for the main thread, and one for each of the threads which is started to compute Pi. | ||
Line 382: | Line 382: | ||
The event tree is a call tree, and can be very useful. From an ENTER or EXIT node in the tree you can use the <EM> | The event tree is a call tree, and can be very useful. From an ENTER or EXIT node in the tree you can use the <EM> | ||
[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | ||
− | [[]]</EM> to: | + | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> to: |
+ | <DIV ID=MARKER-10-780></DIV> | ||
+ | <DIV ID=MARKER-10-781></DIV> | ||
<UL> | <UL> | ||
− | <LI | + | <LI>remove the called function from the set of functions to be traced, |
− | + | <DIV ID=MARKER-10-782></DIV> | |
+ | <LI>find the next reference to the same function in the trace events, or | ||
− | + | <DIV ID=MARKER-10-783></DIV> | |
+ | <DIV ID=MARKER-2-784></DIV> | ||
+ | <LI>go to the function in the <EM> | ||
+ | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> to trace additional information. | ||
</UL> | </UL> | ||
− | + | As you step to each event, the <EM> | |
+ | [["rcc-11.html#MARKER-9-1830">Event Details Pane</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> may show additional information about that event. See | ||
+ | [["rcc-11.html#MARKER-9-1725">"Trace Display"</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] for a more complete description of this window. | ||
− | < | + | <DIV ID=MARKER-2-785></DIV> |
+ | Take some time to explore the event tree. Then we will look at using the information available here to revise or "tune" the trace used in the next run. | ||
<!-- <H3> Call Counts</H3> --> | <!-- <H3> Call Counts</H3> --> | ||
=== Call Counts === | === Call Counts === | ||
− | + | <DIV ID=MARKER-10-786></DIV> | |
+ | Useful information about the functions called in your program may be obtained by looking at the call frequency as shown in the CALL_COUNTS table. | ||
+ | <DIV ID=MARKER-2-787></DIV> | ||
+ | <DIV ID=MARKER-10-788></DIV> | ||
<OL> | <OL> | ||
− | <LI | + | <LI>Select (left-click) the SYN_CALL_COUNTS node, near the end of the event tree. |
− | <LI><P>Right-click (with MB3) to show the <EM>[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV></EM> on this node.</P> | + | <LI><P>Right-click (with MB3) to show the <EM> |
+ | [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> on this node.</P> | ||
− | <LI><P>Click <EM>[["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV></EM>. This will open a table listing each called function<DIV ID=MARKER-10-789></DIV> and the number of times it was called.</P> | + | <LI><P>Click <EM> |
+ | [["rcc-11.html#MARKER-9-1761">Show Associated Table</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>. This will open a table listing each called function<DIV ID=MARKER-10-789></DIV> and the number of times it was called.</P> | ||
<LI><P>Select (left-click) the <CODE>extern:"_start()"<DIV ID=MARKER-10-790></DIV></CODE> entry in the call count table.</P> | <LI><P>Select (left-click) the <CODE>extern:"_start()"<DIV ID=MARKER-10-790></DIV></CODE> entry in the call count table.</P> | ||
− | <LI | + | <LI>Right click to show the popup menu. |
− | <LI | + | <LI>Select <EM> |
+ | [["rcc-11.html#MARKER-9-1746">Deselect Function In Trace Setup</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> in the popup menu. | ||
</OL> | </OL> | ||
− | <P> You can also <EM>[["rcc-11.html#MARKER-9-1759">Find Function In Trace Events</DIV></EM> to search for functions<DIV ID=MARKER-10-791></DIV> in the call tree, and remove them from there.</P> | + | <P> You can also <EM> |
+ | [["rcc-11.html#MARKER-9-1759">Find Function In Trace Events</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> to search for functions<DIV ID=MARKER-10-791></DIV> in the call tree, and remove them from there.</P> | ||
<P> You can also search for functions<DIV ID=MARKER-10-792></DIV> in the call tree, and remove them from there.<DIV ID=MARKER-10-793></DIV></P> | <P> You can also search for functions<DIV ID=MARKER-10-792></DIV> in the call tree, and remove them from there.<DIV ID=MARKER-10-793></DIV></P> | ||
Line 427: | Line 450: | ||
<LI><P>When you've finished making changes to the trace, click the <EM>Dismiss</EM> button at the bottom of the S<DIV ID=MARKER-2-795></DIV>YN_<DIV ID=MARKER-10-796></DIV>CALL_COUNTS table window, and then </P> | <LI><P>When you've finished making changes to the trace, click the <EM>Dismiss</EM> button at the bottom of the S<DIV ID=MARKER-2-795></DIV>YN_<DIV ID=MARKER-10-796></DIV>CALL_COUNTS table window, and then </P> | ||
− | <LI><P>Click the <EM><DIV ID=MARKER-2-797></DIV>[["rcc-11.html#MARKER-9-1427">Build</DIV></EM> button in the main window.</P> | + | <LI><P>Click the <EM><DIV ID=MARKER-2-797></DIV> |
+ | [["rcc-11.html#MARKER-9-1427">Build</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> button in the main window.</P> | ||
<LI><P>Notice the effects of removing these calls in the next trace we generate.</P> | <LI><P>Notice the effects of removing these calls in the next trace we generate.</P> | ||
</OL> | </OL> | ||
− | <P> NOTE: In most "real" programs, high-overhead functions selected for tracing are automatically identified and disabled via [["rcc-6.html#MARKER-9-433">load shedding</DIV>, and are listed in the [["rcc-11.html#MARKER-9-1857">LOAD_SHED Table</DIV> associated with the LOAD_SHED node at the end of the event tree. This demo doesn't run long enough for the load shedding heuristics to apply. See [["rcc-6.html#MARKER-9-374">"RootCause Overhead Management"</DIV> for a general discussion of load shedding.</P> | + | <P> NOTE: In most "real" programs, high-overhead functions selected for tracing are automatically identified and disabled via [["rcc-6.html#MARKER-9-433">load shedding</DIV> |
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]], and are listed in the | ||
+ | [["rcc-11.html#MARKER-9-1857">LOAD_SHED Table</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] associated with the LOAD_SHED node at the end of the event tree. This demo doesn't run long enough for the load shedding heuristics to apply. See | ||
+ | [["rcc-6.html#MARKER-9-374">"RootCause Overhead Management"</DIV> | ||
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]] for a general discussion of load shedding.</P> | ||
<DIV ID=HEADING8-112></DIV> | <DIV ID=HEADING8-112></DIV> | ||
Line 461: | Line 491: | ||
<OL> | <OL> | ||
− | <LI><P>Click the [["rcc-11.html#MARKER-9-1426">Setup</DIV> button in the Workspace Browser to return to the [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV>. </P> | + | <LI><P>Click the |
+ | [["rcc-11.html#MARKER-9-1426">Setup</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] button in the Workspace Browser to return to the | ||
+ | [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]. </P> | ||
− | <P>This is just as in [["#MARKER-9-738">"Define the Trace"</DIV> above, but this time we'll record some details about a specific function<DIV ID=MARKER-10-801></DIV>, <DIV ID=MARKER-10-802></DIV><CODE>::ataninvint<DIV ID=MARKER-10-803></DIV></CODE>.</P> | + | <P>This is just as in |
+ | [["#MARKER-9-738">"Define the Trace"</DIV> | ||
+ | [[]] above, but this time we'll record some details about a specific function<DIV ID=MARKER-10-801></DIV>, <DIV ID=MARKER-10-802></DIV><CODE>::ataninvint<DIV ID=MARKER-10-803></DIV></CODE>.</P> | ||
</OL> | </OL> | ||
Line 475: | Line 511: | ||
<LI><P>Expand the <DIV ID=MARKER-2-805></DIV>pi.cpp<DIV ID=MARKER-2-806></DIV><DIV ID=MARKER-10-807></DIV> node to see the methods.</P> | <LI><P>Expand the <DIV ID=MARKER-2-805></DIV>pi.cpp<DIV ID=MARKER-2-806></DIV><DIV ID=MARKER-10-807></DIV> node to see the methods.</P> | ||
− | <LI><P>Select the <CODE>ataninvint</CODE> method. This will bring up the source code for this method in the [["rcc-11.html#MARKER-9-1574">Source Pane</DIV>, and show a tree of data to log in <CODE>ataninvint </CODE><DIV ID=MARKER-10-808></DIV>in the <EM>[["rcc-11.html#MARKER-9-1579">Variables Pane</DIV></EM>.</P> | + | <LI><P>Select the <CODE>ataninvint</CODE> method. This will bring up the source code for this method in the |
+ | [["rcc-11.html#MARKER-9-1574">Source Pane</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]], and show a tree of data to log in <CODE>ataninvint </CODE><DIV ID=MARKER-10-808></DIV>in the <EM> | ||
+ | [["rcc-11.html#MARKER-9-1579">Variables Pane</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>.</P> | ||
</OL> | </OL> | ||
Line 497: | Line 537: | ||
<OL> | <OL> | ||
− | <LI><P>In that same lower-right area, click on the <EM><DIV ID=MARKER-2-813></DIV>Probes</EM> tab to show the <EM>[["rcc-11.html#MARKER-9-1589">Probes Pane</DIV></EM>. Probes in this context are special [["rcc-6.html#MARKER-9-396">actions</DIV> that can be performed at points in the currently selected function<DIV ID=MARKER-10-814></DIV>. </P> | + | <LI><P>In that same lower-right area, click on the <EM><DIV ID=MARKER-2-813></DIV>Probes</EM> tab to show the <EM> |
+ | [["rcc-11.html#MARKER-9-1589">Probes Pane</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM>. Probes in this context are special | ||
+ | [["rcc-6.html#MARKER-9-396">actions</DIV> | ||
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]] that can be performed at points in the currently selected function<DIV ID=MARKER-10-814></DIV>. </P> | ||
<LI><P>Click the "On" checkbox.</P> | <LI><P>Click the "On" checkbox.</P> | ||
Line 515: | Line 559: | ||
<P> We've now requested that the parameter X <DIV ID=MARKER-10-817></DIV>be logged (recorded) on entry to method <DIV ID=MARKER-10-818></DIV><CODE>ataninvint</CODE>, and also that a data snapshot be taken at this point and marked with the Event Name "My Snapshot". </P> | <P> We've now requested that the parameter X <DIV ID=MARKER-10-817></DIV>be logged (recorded) on entry to method <DIV ID=MARKER-10-818></DIV><CODE>ataninvint</CODE>, and also that a data snapshot be taken at this point and marked with the Event Name "My Snapshot". </P> | ||
− | <P> <EM>Note</EM>: A snapshot causes data which might otherwise be deleted do to "data wraparound" to be preserved. In this small demo, a snapshot is not really necessary since it doesn't generate enough data to wrap around and cause old data to be lost. See [["rcc-6.html#MARKER-9-371">"Data Snapshots"</DIV> for more information.</P> | + | <P> <EM>Note</EM>: A snapshot causes data which might otherwise be deleted do to "data wraparound" to be preserved. In this small demo, a snapshot is not really necessary since it doesn't generate enough data to wrap around and cause old data to be lost. See |
+ | [["rcc-6.html#MARKER-9-371">"Data Snapshots"</DIV> | ||
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]] for more information.</P> | ||
<!-- <H3> Save and Build the Trace</H3> --> | <!-- <H3> Save and Build the Trace</H3> --> | ||
Line 521: | Line 567: | ||
<OL> | <OL> | ||
− | <LI><P>Click the <EM>OK</EM> button at the bottom right of the dialog to save and build the trace and dismiss the Trace Setup dialog. Note that this will take a bit longer this time because we've created Probe [["rcc-6.html#MARKER-9-396">actions</DIV> that require compilation of an [["rcc-6.html#MARKER-9-390">APC</DIV> file.</P> | + | <LI><P>Click the <EM>OK</EM> button at the bottom right of the dialog to save and build the trace and dismiss the Trace Setup dialog. Note that this will take a bit longer this time because we've created Probe |
+ | [["rcc-6.html#MARKER-9-396">actions</DIV> | ||
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]] that require compilation of an | ||
+ | [["rcc-6.html#MARKER-9-390">APC</DIV> | ||
+ | [[RCUG_3_Terminology_and_Concepts|CHAPTER 3 - Terminology and Concepts]] file.</P> | ||
</OL> | </OL> | ||
Line 529: | Line 579: | ||
<OL> | <OL> | ||
− | <LI><P>Again, check that rootcause is enabled with either the [["rcc-12.html#MARKER-9-2094">rootcause_on</DIV> or [["rcc-12.html#MARKER-9-2129">rootcause status</DIV> command. Then run the application by running the pi_demo program<DIV ID=MARKER-10-820></DIV>, as described in [["#MARKER-9-759">"Trace With RootCause"</DIV>.</P> | + | <LI><P>Again, check that rootcause is enabled with either the |
+ | [["rcc-12.html#MARKER-9-2094">rootcause_on</DIV> | ||
+ | [[RCUG_RootCause_Command_Reference|CHAPTER 9 - RootCause Command Reference]] or | ||
+ | [["rcc-12.html#MARKER-9-2129">rootcause status</DIV> | ||
+ | [[RCUG_RootCause_Command_Reference|CHAPTER 9 - RootCause Command Reference]] command. Then run the application by running the pi_demo program<DIV ID=MARKER-10-820></DIV>, as described in | ||
+ | [["#MARKER-9-759">"Trace With RootCause"</DIV> | ||
+ | [[]].</P> | ||
</OL> | </OL> | ||
Line 536: | Line 592: | ||
<OL> | <OL> | ||
− | <LI><P>Click the <EM>[["rcc-11.html#MARKER-9-1431">Index</DIV></EM> button in the Workspace Browser window. </P> | + | <LI><P>Click the <EM> |
+ | [["rcc-11.html#MARKER-9-1431">Index</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> button in the Workspace Browser window. </P> | ||
<LI><P>In the Trace Index Dialog that comes up, double-click on the SNAP entry labeled "My Snapshot" to go right to where our new probes were added.</P> | <LI><P>In the Trace Index Dialog that comes up, double-click on the SNAP entry labeled "My Snapshot" to go right to where our new probes were added.</P> | ||
Line 548: | Line 606: | ||
=== Find the Calls Of Interest === | === Find the Calls Of Interest === | ||
− | + | The Trace Display window opened from the Trace Index Dialog operation will contain many events, including other calls to <CODE>ataninvint</CODE>. | |
<OL> | <OL> | ||
− | <LI | + | <LI>With the "ENTER ataninvint" node selected, right-click to show the <EM> |
+ | [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]] and choose | ||
+ | [["rcc-11.html#MARKER-9-1759">Find Function In Trace Events</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]].</EM> | ||
− | < | + | <DIV ID=MARKER-10-822></DIV> |
+ | <LI>This will bring up the <EM> | ||
+ | [["rcc-11.html#MARKER-9-1842">Find Text in Trace Events Dialog</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> with the current function name filled in. Click Next, and the next occurrence of this string will be selected. Thereafter you can continue clicking <EM>Next</EM>, or enter any other string to search for. You can use <EM> | ||
+ | [["rcc-11.html#MARKER-9-1763">Find Text in Trace Events</DIV> | ||
+ | [[RCUG_RootCause_GUI_Reference|CHAPTER 8 - RootCause GUI Reference]]</EM> from any the popup or Edit menu to search for any string in the current Trace Display. | ||
</OL> | </OL> | ||
Line 565: | Line 632: | ||
== Where To From Here? == | == Where To From Here? == | ||
− | + | This chapter should have given you a good overview of the process of developing a trace and gathering data for a program. Now you're ready to try it on your own application. The application you use should be a "debug build" so Trace Setup has the information it needs. See | |
+ | [["rcc-13.html#MARKER-9-2163">"Selected Topics"</DIV> | ||
+ | [[RCUG_7_Selected_Topics|CHAPTER 10 - Selected Topics]]. | ||
<DIV ID="LINK-05demo_rc.fm-lastpage"></DIV> | <DIV ID="LINK-05demo_rc.fm-lastpage"></DIV> |
Revision as of 19:13, 3 November 2017
RootCause User Guide
Contents
RootCause Demo
RCUG 5 RootCause Demo
rcc-8
This demonstration program, included as part of the RootCause installation, has been designed to provide an introduction and overview of the RootCause product. The program is:
$APROBE/demo/RootCause/C++/pi_demo
It is a simple 2-file C++ program, which computes the value of Pi by iteration using multiple threads. You can find the source in the same directory as the executable file.
The goal of this demonstration is to provide an overview of the whole RootCause process, showing initial definition and tuning of the trace, then collection and viewing of more detailed data about a specific function. The demonstration pictured in this chapter was performed on Solaris. Output should be very similar on AIX and Linux.
Set Up
Before running this RootCause Demo, you must install and set up to use RootCause as described in
[["rcc-7.html#MARKER-9-508">Chapter 4, "Getting Started"
Chapter 4, "Getting Started". This will define the APROBE environment variable which is necessary to use RootCause.
In the instructions that follow, we'll use $APROBE
to refer to the path where RootCause is installed, for example /opt/aprobe.
Use a Local Disk
We recommend you set your current directory to a disk local to the machine you're running on, though this is not required.
Defined X-Windows DISPLAY
Lastly, make sure your DISPLAY environment variable is set. If you're using a Windows client that is running X emulator software such as eXceed or Reflection, we recommend you move to a Unix display for your initial evaluation. If this is impractical, see
[["rcc-11.html#MARKER-9-1878">"X-emulators: (Exceed, Reflection)"
CHAPTER 8 - RootCause GUI Reference.
Run With RootCause
Run the following commands:
rootcause_on $APROBE/demo/RootCause/C++/pi_demo <DIV ID=MARKER-10-714></DIV>rootcause_off
The rootcause_on
command enables the automatic logging of every process that is started, and rootcause_off
disables this logging. When the pi_demo program is "
[["rcc-6.html#MARKER-9-451">register
CHAPTER 3 - Terminology and Conceptsed" with RootCause, it will be traced according to your specifications as well as simply being logged. The illustration below shows the set up and demo execution..
NOTE: On AIX, the above process is slightly different than shown above. The invocation of the program must be done with the
[["rcc-12.html#MARKER-9-2119">rootcause run
CHAPTER 9 - RootCause Command Reference command directly. For example, the above sequence is changed to:
rootcause run $APROBE/demo/RootCause/C++/pi_demo
See
[["rcc-7.html#MARKER-9-532">"Enabling RootCause for an AIX Application"
"Enabling RootCause for an AIX Application".
View the RootCause Log
Enter the following command:
rootcause open
This will open the RootCause main window, and then a view of the RootCause log. This shows the
[["rcc-11.html#MARKER-9-1725">Trace Display
CHAPTER 8 - RootCause GUI Reference window, the window for viewing all trace events. On the left is the Event Tree; on the upper right is the source/text window; and on the lower right is the "details" window. In the text window you will see some information about the log file.
Locate the APP_START event (in the Trace Event window) associated with the pi_demo
program run earlier. To view information about this event, select the APP_START node in the event tree with a left click. This will fill in "details" about that event in the lower right window.With the APP_START pi_demo node highlighted, right-click to bring up the
[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu
CHAPTER 8 - RootCause GUI Reference.
Click
[["rcc-11.html#MARKER-9-1730">Open Associated Workspace
CHAPTER 8 - RootCause GUI Reference in the popup-menu of the pi_demo APP_START event.
This will open a
[["rcc-11.html#MARKER-9-1434">New Workspace Dialog
CHAPTER 8 - RootCause GUI Reference with the program name and default workspace filled in.
This combination: selecting a node in the tree, then using the popup menu to choose an operation, is the basic way of working within RootCause.
Create a RootCause Workspace
To complete the creation of a RootCause workspace for the pi_demo application:
- Click Ok in the New Workspace dialog to complete the creation of the workspace.
- Click Yes to confirm that you want to register the pi_demo application with this workspace. This registration is how RootCause determines what applications to trace.
You may close the RootCause Log window opened in a previous step.
You now see the RootCause
[["rcc-11.html#MARKER-9-1321">Workspace Browser
CHAPTER 8 - RootCause GUI Reference. This is described in detail in
[["rcc-11.html#MARKER-9-1320">Chapter 8, "RootCause GUI Reference"
CHAPTER 8 - RootCause GUI Reference.
Define the Trace
There are several aspects to a RootCause trace:
- Predefined UALs selected from the [["rcc-11.html#MARKER-9-1323">Workspace Tree
- Method and Line traces selected from the [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog
- Probes to gather or preserve data, also selected in the [["rcc-11.html#MARKER-9-1531">Trace Setup Dialog
- User-written custom probes as described in [["rcc-13.html#MARKER-9-2198">"Writing Custom Probes"
In this part of the demo we illustrate the use of Predefined UALs and tracing function calls; then we'll return to the Trace Setup Dialog to add some probes. Custom probes are an advanced feature not presented here.
In the RootCause GUI main window, opened in the previous section:
Enable a UAL
Under the
[["rcc-11.html#MARKER-9-1330">UALs node
CHAPTER 8 - RootCause GUI Reference in the
[["rcc-11.html#MARKER-9-1323">Workspace Tree
CHAPTER 8 - RootCause GUI Reference:
- Check the checkbox next to predefined UAL labeled
exceptions.ual
, as highlighed in the figure above. Simply checking this box will report all user-defined C++ (and Ada) exceptions.
Define Function Traces
Now we'll add traces specific to this application.
- Click on the
[["rcc-11.html#MARKER-9-1426">Setup
CHAPTER 8 - RootCause GUI Reference button in the button bar.
This will open the
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog
CHAPTER 8 - RootCause GUI Reference, showing the modules of the application in the
[["rcc-11.html#MARKER-9-1533">Program Contents Tree
CHAPTER 8 - RootCause GUI Reference. The
[["rcc-11.html#MARKER-9-1533">Program Contents Tree
CHAPTER 8 - RootCause GUI Reference identifies the modules, files, functions, methods, and data in the program, and allows you to specify complex actions on each function and method.
For this demo we'll first just specify a trace on the functions in the file pi_demo.cpp
, then return later to add data and probes.
- Click on the "lever" icon next to the
pi_demo
module to expand it; then expand the/tmp/demo
directory, so you see the nodes for the source filespi.cpp
andpi_demo.cpp.
- Click on the
pi_demo.cpp
source file node, then right-click to see the [["rcc-11.html#MARKER-9-1545">Trace Setup Popup Menu - Click
[["rcc-11.html#MARKER-9-1557">Trace All In
CHAPTER 8 - RootCause GUI Reference pi_demo.cpp.
- Click the OK button at the bottom right of the dialog to record the trace and dismiss the Trace Setup dialog.
Trace With RootCause
As was done in the preceding section,
[["#MARKER-9-713">"Run With RootCause"
[[]], run the following commands:
rootcause_on $APROBE/demo/RootCause/C++/pi_demo rootcause_off
Or, for AIX:
rootcause run $APROBE/demo/RootCause/C++/pi_demo
This time, since the program is registered with a workspace, it will be traced as specified in the workspace, and the resulting output will be recorded within the workspace. There will be some startup delay, but if you notice that the program runs slower once started, this is probably because your workspace is being accessed across the network from your machine. See
[["rcc-13.html#MARKER-9-2164">"RootCause and Efficiency Concerns"
View The Data Index
We're now ready to view the data generated by running with our Trace. This is discussed in detail in
[["rcc-6.html#MARKER-9-366">"RootCause Data Management"
CHAPTER 3 - Terminology and Concepts.
In the
[["rcc-11.html#MARKER-9-1321">Workspace Browser
CHAPTER 8 - RootCause GUI Reference window, do the following:
- Click the
[["rcc-11.html#MARKER-9-1431">Index
CHAPTER 8 - RootCause GUI Reference button. This will bring up the
[["rcc-11.html#MARKER-9-1680">Trace Index DialogCHAPTER 8 - RootCause GUI Reference for the most recently generated data.
- In the Trace Index Dialog, click the [["rcc-11.html#MARKER-9-1699">Select Events
- In the
[["rcc-11.html#MARKER-9-1711">Select Events Dialog
CHAPTER 8 - RootCause GUI Reference, check "Exceptions" to index exception events, then click
[["rcc-11.html#MARKER-9-1718">UpdateCHAPTER 8 - RootCause GUI Reference to close the dialog and refresh the Index. You should now see something like the dialog below:
- In the Trace Index Dialog, double-click on the second item in the table, the first item with an Event name of C++ EXCEPTION.
This will open a Trace Display Dialog centered at that C++ Exception event, as shown below.
Examine and Revise the Trace
The C++ Exception trace event selected from the index should appear highlighted in the Trace Display. This was a result of checking exceptions under
[["#MARKER-9-741">"Enable a UAL"
[[]] above.
The ENTER and EXIT nodes are a result of the "Trace All In pi_demo.exe" action added under
[["#MARKER-9-744">"Define Function Traces"
[[]] above.
You can see more information about the exception in the
[["rcc-11.html#MARKER-9-1830">Event Details Pane
CHAPTER 8 - RootCause GUI Reference in the lower right.
If you scroll to the top of the Event Trace, you should see three threads: one for the main thread, and one for each of the threads which is started to compute Pi.
The event tree is a call tree, and can be very useful. From an ENTER or EXIT node in the tree you can use the
[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu
CHAPTER 8 - RootCause GUI Reference to:
- remove the called function from the set of functions to be traced,
- find the next reference to the same function in the trace events, or
- go to the function in the
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog
CHAPTER 8 - RootCause GUI Reference to trace additional information.
As you step to each event, the
[["rcc-11.html#MARKER-9-1830">Event Details Pane
CHAPTER 8 - RootCause GUI Reference may show additional information about that event. See
[["rcc-11.html#MARKER-9-1725">"Trace Display"
CHAPTER 8 - RootCause GUI Reference for a more complete description of this window.
Take some time to explore the event tree. Then we will look at using the information available here to revise or "tune" the trace used in the next run.
Call Counts
Useful information about the functions called in your program may be obtained by looking at the call frequency as shown in the CALL_COUNTS table.
- Select (left-click) the SYN_CALL_COUNTS node, near the end of the event tree.
Right-click (with MB3) to show the [["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu CHAPTER 8 - RootCause GUI Reference on this node.
Click [["rcc-11.html#MARKER-9-1761">Show Associated Table CHAPTER 8 - RootCause GUI Reference. This will open a table listing each called function
and the number of times it was called.Select (left-click) the
entry in the call count table.extern:"_start()"
- Right click to show the popup menu.
- Select
[["rcc-11.html#MARKER-9-1746">Deselect Function In Trace Setup
CHAPTER 8 - RootCause GUI Reference in the popup menu.
You can also [["rcc-11.html#MARKER-9-1759">Find Function In Trace Events CHAPTER 8 - RootCause GUI Reference to search for functions
in the call tree, and remove them from there.
You can also search for functions
in the call tree, and remove them from there.
When you've finished making changes to the trace, click the Dismiss button at the bottom of the S
YN_CALL_COUNTS table window, and thenClick the
[["rcc-11.html#MARKER-9-1427">Build CHAPTER 8 - RootCause GUI Reference button in the main window.Notice the effects of removing these calls in the next trace we generate.
NOTE: In most "real" programs, high-overhead functions selected for tracing are automatically identified and disabled via [["rcc-6.html#MARKER-9-433">load shedding
CHAPTER 3 - Terminology and Concepts, and are listed in the
[["rcc-11.html#MARKER-9-1857">LOAD_SHED Table
CHAPTER 8 - RootCause GUI Reference associated with the LOAD_SHED node at the end of the event tree. This demo doesn't run long enough for the load shedding heuristics to apply. See
[["rcc-6.html#MARKER-9-374">"RootCause Overhead Management" CHAPTER 3 - Terminology and Concepts for a general discussion of load shedding.
Tracing The Details
So far we have seen how the RootCause process works by:
enabling a predefined UAL (
exceptions);defining a simple trace from the Trace Setup Dialog;
running the application under RootCause;
choosing an event in the Trace Index Dialog;
viewing events in the Trace Display; and
modifying the trace by selecting functions
from the call counts table.
RootCause allows you to record much more than the entry and exit of functions
and threads. You can record data values and insert probes as well.
Open Trace Setup
Click the [["rcc-11.html#MARKER-9-1426">Setup
CHAPTER 8 - RootCause GUI Reference button in the Workspace Browser to return to the
[["rcc-11.html#MARKER-9-1531">Trace Setup Dialog CHAPTER 8 - RootCause GUI Reference.This is just as in [["#MARKER-9-738">"Define the Trace" [[]] above, but this time we'll record some details about a specific function
,::ataninvint
.
Select A Single Function
Click the "lever" to expand the M pi_demo node to see the Source Files in the module.
Expand the
pi.cpp node to see the methods.Select the
in the [["rcc-11.html#MARKER-9-1579">Variables Pane CHAPTER 8 - RootCause GUI Reference.ataninvint
method. This will bring up the source code for this method in the [["rcc-11.html#MARKER-9-1574">Source Pane CHAPTER 8 - RootCause GUI Reference, and show a tree of data to log inataninvint
Log Parameters
Check the box for variable X in the Visible On Entry subtree, and for the return value in the Visible On Exit subtree.
Add a Snapshot Probe
In that same lower-right area, click on the
Probes tab to show the [["rcc-11.html#MARKER-9-1589">Probes PaneCHAPTER 8 - RootCause GUI Reference. Probes in this context are special
[["rcc-6.html#MARKER-9-396">actions CHAPTER 3 - Terminology and Concepts that can be performed at points in the currently selected function.Click the "On" checkbox.
Where it says No Trigger, select Function Entry.
Where it says No Action, select
Log Snapshot.Where it says ROOTCAUSE_SNAPSHOT, select this and type in "My Snapshot" and hit Enter.
We've now requested that the parameter X
be logged (recorded) on entry to method
ataninvint
, and also that a data snapshot be taken at this point and marked with the Event Name "My Snapshot".
Note: A snapshot causes data which might otherwise be deleted do to "data wraparound" to be preserved. In this small demo, a snapshot is not really necessary since it doesn't generate enough data to wrap around and cause old data to be lost. See [["rcc-6.html#MARKER-9-371">"Data Snapshots" CHAPTER 3 - Terminology and Concepts for more information.
Save and Build the Trace
Click the OK button at the bottom right of the dialog to save and build the trace and dismiss the Trace Setup dialog. Note that this will take a bit longer this time because we've created Probe [["rcc-6.html#MARKER-9-396">actions
CHAPTER 3 - Terminology and Concepts that require compilation of an
[["rcc-6.html#MARKER-9-390">APC CHAPTER 3 - Terminology and Concepts file.
Run With RootCause
Again, check that rootcause is enabled with either the [["rcc-12.html#MARKER-9-2094">rootcause_on
CHAPTER 9 - RootCause Command Reference or
[["rcc-12.html#MARKER-9-2129">rootcause status CHAPTER 9 - RootCause Command Reference command. Then run the application by running the pi_demo program, as described in [["#MARKER-9-759">"Trace With RootCause" [[]].
Index the New Trace
Click the [["rcc-11.html#MARKER-9-1431">Index CHAPTER 8 - RootCause GUI Reference button in the Workspace Browser window.
In the Trace Index Dialog that comes up, double-click on the SNAP entry labeled "My Snapshot" to go right to where our new probes were added.
Select the "ENTER ataninvint" node immediately preceding the Snapshot node to see the value of x
on entry.Select the corresponding "EXIT ataninvint" node following the Snapshot to see the return value on exit.
Find the Calls Of Interest
The Trace Display window opened from the Trace Index Dialog operation will contain many events, including other calls to ataninvint
.
- With the "ENTER ataninvint" node selected, right-click to show the
[["rcc-11.html#MARKER-9-1826">Trace Display Popup Menu
CHAPTER 8 - RootCause GUI Reference and choose
[["rcc-11.html#MARKER-9-1759">Find Function In Trace Events - This will bring up the
[["rcc-11.html#MARKER-9-1842">Find Text in Trace Events Dialog
CHAPTER 8 - RootCause GUI Reference with the current function name filled in. Click Next, and the next occurrence of this string will be selected. Thereafter you can continue clicking Next, or enter any other string to search for. You can use
[["rcc-11.html#MARKER-9-1763">Find Text in Trace EventsCHAPTER 8 - RootCause GUI Reference from any the popup or Edit menu to search for any string in the current Trace Display.
Where To From Here?
This chapter should have given you a good overview of the process of developing a trace and gathering data for a program. Now you're ready to try it on your own application. The application you use should be a "debug build" so Trace Setup has the information it needs. See
[["rcc-13.html#MARKER-9-2163">"Selected Topics"
Copyright 2006-2017 OC Systems, Inc.