Using TraceGraph 4

This document provides a quick introduction to TraceGraph 4, and a tutorial example using a "canned" set of trace files from the Apache Web Server. The trace files can be loaded by choosing "Apache Web Server Traces" from the Demos menu.

Contents:

• Introduction
• Tutorial Example - Apache Web Server
  
• Using TraceGraph 4 and Klocwork (Exporting)
  
• Using TraceGraph 4 and Eclipse

Introduction

The TraceGraph 4 tool, allows a Software Engineer to do Software Reconnaissance visually starting from a set of trace files for different test cases. In TraceGraph:

1. You choose "open a trace source" from the file menu, and then respond to the prompts in a dialog to tell TraceGraph how to read the traces and what format they have.
2. TraceGraph then loads your traces and lets you compare them so you can decice what code you need to study.
3. You then study the code and make your changes using your editor, a browsing tool such as Klocwork (TM Klocwork Inc.), or a development environment such as Eclipse (TM Eclipse Foundation).

To take a very simple example, suppose we have a calculator program that does add, subtract, divide and multiply. We want to know: "Where is the multiply function implemented?"

We could instrument the source code of the calculator using, for example, the RECON3 instrumentor for C/C++. We then compile the instrumented code. (See UWF's RECON3 web site for information on this free instrumentor.) We would then run four test cases, each of which does just one of the four operations. Each of the four test cases gives us a trace file. We put the four trace files in an empty directory and we rename them so that the multiply file is the last one in alphabetical order. (TraceGraph reads in the files in alphabetical order. We put the multiply file in last so that TraceGraph can easily show us the events that are only in that file.) We would then start TraceGraph 4. From the File menu we select "Open a Trace Source" and in the next dialog pick a "fixed directory" type trace source and navigate to the directory containing the trace files. For the trace format pick "RECON3". We would see a window like Figure 1 to the right. The TraceGraph display has one column of rectangles for each trace file. A dark rectangle indicates that a particular bit of code was executed in that period. The rectangle is red the first test in which the code was executed and black in later tests.

Fig. 1 - TraceGraph 4 Screen Shot

Since we know that multiply was only done in the last test, we look for red rectangles in the last column. Sure enough, there are three such rectangles. We right mouse on the first of them and pick "show row information window". The pop-up window (Figure 2) tells us that this was an entry to a function called multiply in file operations.c. So we have found the code for the multiply feature!

Fig. 2 - Row Information Window

TraceGraph 4 can give you a quick overview of how a feature is distributed within a large system. We will see how that works in the next example.

Tutorial Example - Apache Web Server

Apache is a well known web server used on many web sites around the world. As part of our on-line demo of RECON3 (at http://www.cs.uwf.edu/~recon/recon3/r3wDemo.htm) Apache has been instrumented using the Recon3 C/C++ instrumentor so that trace information is generated on each function entry and return. Some trace files from that demo have been saved for distribution with TraceGraph 4.

This version of Apache (1.3.20) was about 70,000 lines of code with numerous features. One of these is the ability to display a directory listing; if you enter the URL of a directory in your web browser, the server will show you a listing of the files it contains. This is the feature we are going to look for.

If you have installed TraceGraph 4, the traces are in the demofiles/apacheTraces01 directory. Each trace file represents about five seconds of processing. Here is a sample record from one of the trace files:

E 10 0 0 0 2542 0 1 * 52 /usr/u/nwdemo/apache_1.3.20/src/main/http_protocol.c 9 ap_rvputs

This record shows that, in the five second period, the function ap_rvputs was called ("Entered") 10 times. The function starts on line number 2542 of file http_protocol.c.

To view the traces in TraceGraph choose "Apache Web Server Traces" from the "Demos" menu. When you do so you should (after a few seconds) get an image similar to the one to the right (Figure 3). We have selected the "Tiny" scale to get an overview of how the code for the feature is distributed in this large system. The background shading shows the different source files. The traces show: First 12 columns (trace files ds1520881.r3t to ds1520892.r3t) Apache just "ticking over" waiting for an incoming request. Column 13 (trace file ds1520893.r3t) Apache is processing a request for a simple HTML page with a few lines of formatted text. Columns 14 and 15 (files ds1520894.r3t and ds1520895.r3t) Apache is again in its wait state. Columns 16 and 17 (files ds1520896.r3t and ds1520897.r3t) Apache is processing a request that requires generating and formatting a listing of a directory. You can see that there are numerous red rectangles, especially in the 17th column. If you scroll up and down, you can see how the code for the feature is distributed. You will find two source files that have all their rectangles red in colum 17 so these would be good places to start looking for directory listing code.

Fig. 3 - TraceGraph 4 Showing Apache Traces

If you select the Normal scale you can make the window wider (Figure 4) and see the details for each rectangle in the center columns without having to bring up the Row Information Window for each one.

Using TraceGraph 4 and Klocwork (Exporting)

Once you have found a set of rows (trace events) that you want to study, the TraceGraph "Export" menu can help you make a list of them or export them to a code browsing tool such as Klocwork. Here are the specific steps for working with Klocwork. We assume that you have purchased a Klocwork license and know how to run the Klocwork Insight tool.

We will continue using the Apache listing of a directory example from the previous section. You would first have created a Klocwork "build" to load Apache's source code into Klocwork's data base. If you wish to create such a build that matches our traces, the original Apache source code is in the file apache_1.3.20_src.zip (for Windows users) and in apache_1.3.20_src.tar.Z (for Unix users). Since column 17 seems to be showing us the important code for listing of a directory, we want to tell Klocwork to create a "custom diagram" focusing on that code. Right mouse on column 17 and choose from the popup menu "Set Checkboxes for Red Rectangles". Checkboxes should appear in all the rows with red rectangles in that column (Figure 5). You could check or uncheck additional rows by hand if you wish to include / exclude them. From the Export menu choose "Export Checked Rows to XML File" and use the resulting dialog to specify where you want the file to go.

Figure 5 - Setting Checkboxes for Export  (Click to Enlarge)

The resulting XML file will have one entry for each distinct C function that had a checked event. Note that Klocwork does not distinguish lines within a function, so that there could be several different trace events that result in a single entry in the file. Start Klocwork Insight and open the project with the Klocwork build for Apache. Then from the File menu choose Import from XML and navigate to the XML file created by TraceGraph. When prompted, enter a name for the new custom diagram you are creating. The new custom diagram should appear in the left panel of Insight. Open it to see the functions containing the code you checked in TraceGraph (Figure 6). Klocwork lets you explore the data flow and control relationships in the code and thus helps you understand how the feature is implemented.

Figure 6 - Exploring Code in Klocwork (Click to Enlarge)

Using TraceGraph 4 and Eclipse

If you use the Eclipse development environment, TraceGraph can be used to guide browsing of the code for a feature. (Figure 7)


To use TraceGraph with Eclipse, you will need to install Eclipse and the C/C++ tools. It is beyond the scope of this tutorial to provide an introduction to Eclipse; we suggest that new users browse the Eclipse web site at http://www.eclipse.org. If you are already an Eclipse user but have not used the C/C++ tools, you can install them using the "Software Updates" link on the Eclipse "Help" menu.

This example was prepared using Eclipse 3.2. Menus, etc. may not be the same in your version.

You will also need the TraceGraph 4 Eclipse plug-in jar file from the RECON4 web site. The most common way to install Eclipse plugins is to simply put the jar file in the eclipse/plugins directory and then restart Eclipse. (Remove any previous version first.) To check that the plugin has been loaded, in Eclipse choose Window >> Preferences. You should see tg4eclipse in the left panel of the Preferences dialog.

We will continue using the Apache listing of a directory example from the previous two sections.
You first need to create an Eclipse project for the apache code. The steps are as follows:

1. Extract the code from the file demofiles/apache_1.3.20_src.zip (for Windows users) or in demofiles/apache_1.3.20_src.tar.Z (for Unix users). Locate the "src" directory containg the C source.
2. From the Eclipse "File" menu choose "new" >> "project" >> "C" >> "Standard make C project".
3. In the next dialog, give the project a name and set the location as that "src" directory you found earlier.
4. The new project should open, and you should be able to browse the different C source files.
   

Leave Eclipse running with the Apache project open.

Now start TraceGraph (if not done earlier) and select "Demos" >> "Apache Web Server Traces". After a few seconds you should again see something like Figure 4.

Right mouse on any of the red rectangles and pick "Open In Eclipse" >> "Open File In Eclipse".  The first time you do this you will get a dialog that says "TraceGraph was unable to locate file.c".  This happens because the source file path in the trace file comes from our computer and will not point to the src directory you created when you extracted the Apache source files. You should browse your src directory until you choose the right file, TraceGraph will ask you if you want it to remember that new path and use it in the future. (You may need to repeat the dialog when you switch to looking at code in a different directory.)

Then Eclipse will open the source file and scroll to the right line. You can then use all Eclipse's tools to browse and explore the code for the feature.