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.
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
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
We could instrument the source code of the calculator using,
example, the RECON3 instrumentor for C/C++. We then compile the
instrumented code. (See UWF's RECON3 web site for information on this
We would then run four test cases, each of which does just one
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
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.
|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
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_rvputsThis 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)
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:
Fig. 3 - TraceGraph 4 Showing Apache Traces
|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
(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)
|This example was prepared using Eclipse 3.2. Menus, etc. may not be the same in your version.|