Aprobe Demo

Just Probe It

Start the demo by running Trace, one of Aprobe's Predefined Probes. If you have any problems e-mail support@ocsystems.com or call us at +1 703 359 8160.

Build the Demo Program

You can quickly compile the example and build the probe as follows: 
   cd $APROBE/demo/Aprobe/C
   make
or
   make -f Makefile.gcc
If "make" isn't in your path, use "/usr/ccs/bin/make". If errors are encountered, check that Aprobe is set up properly as described in $APROBE/demo/Aprobe/README.

The demo program, demo.c, is a small program that does a few memory allocations. There is nothing special about demo.c; it could be any program.

Execution Tracing

Do the following:
  1. Run the program with the "trace" predefined probe:
    aprobe -u trace demo.exe
  2. Format the trace of executed functions within demo.exe:
    apformat demo | more

IMPORTANT NOTE: if you really want to trace events in your application, you should use the RootCause product built on top of Aprobe, which provides an extensive GUI and many useful features for defining, gathering, and viewing traces and other details about your program.

Performance Profiling

Now, we'll try profiling:
  1. Run the program with the "profile" predefined probe:
    aprobe -u profile demo.exe
  2. Format the timing data, showing the elapsed time for each function:
    apformat demo | more

Memory Allocation

Now, run memwatch, another of Aprobe's Predefined Probes:
  1. Run demo.exe under Aprobe. The program demo.exe can be passed a parameter, so we will pass it "2". Notice that we are also passing the "-g" option to memwatch. This will tell memwatch to invoke a Java GUI to display data while the program executes:
    aprobe -u memwatch -p -g demo.exe 2
  2. Watch the memory allocation graphs window for a while. This will display heap allocations and deallocations.
  3. Click Close at the bottom of the graphs window when you're finished.
  4. Format the allocation data to get a report of all outstanding heap allocations (i.e. what data did not get freed):
    apformat demo | more

What You Just Did

You saw a very brief overview of some of the predefined probes that form a part of the Aprobe product. The predefined probes can do so much more, and you can also write custom probes of your own.

If you ran into any problems, please contact support@ocsystems.com (or call us at +1 703 359 8160).

The predefined probes are:

The steps above led through all of these except for statprof and coverage. The statprof probe does statistical profiling for which this trivial demo program is too quick. The coverage probe is demonstrated below, where we will run a small "custom" probe in combination with this predefined line coverage probe to get 100% test coverage.

Each predefined probe has a similar interface. Where substantial configuration is available, the user can request a Java GUI with which to specify the configuration. The configuration is defined in a readable file with an extension of ".cfg", and you can directly edit that file to change options if you decide not to use the GUI. However, each probe has a good set of defaults to allow you to use it "out-of-the-box", as we did above.

These predefined probes are just the beginning -- you can write your own custom probes, as described in the next section.

Custom Probes

The predefined probes that you have seen provide useful capabilities in an easy to use manner. Aprobe, however, provides the capability to write custom probes specific to your application. This last portion of the demo will demonstrate this.

Examine the file "demo.apc", reproduced below. 

//
// This apc file will force the malloc call to return a NULL value 
// (indicating no more memory available) after malloc is called five
// times from within AllocateOne.
//

int count = 0;

probe thread
{
  probe extern:"AllocateOne()" 
  {
    probe extern:"malloc()" in "libc.a(shr.o)"
    { 
      on_entry
        count++;

      on_exit
        if (count > 5)
          $return = NULL;
    }
  }
}

The aprobe patching language is C, with a few extra keywords added (probe, on_entry, on_exit and on_line). The "patches", or probes, that are defined in demo.apc were compiled when you ran "make" above, producing demo.ual. These probes cause malloc to return a 0 after it is called the fifth time from within the routine AllocateOne. In the demo, this will cause a different path to be executed, so we can test that path.

To run the demo with this probe (demo.ual), so just as we did above, but using "demo": 

aprobe -u demo demo.exe
We see that it displays "out of memory" because our custom probe modified the address returned by "malloc()" to be NULL. (There's no need to run apformat since it doesn't log any data.)

Combining Predefined and Custom Probes

By combining the test coverage probe and our custom probe, we can force all lines in the demo to be executed.
  1. Run the coverage predefined probe on demo.exe:
    aprobe -u coverage demo.exe
  2. Format the results:
    apformat demo
At the end of the report we see that lines 26 .. 27 of "main" were not executed.

Now let's run it again for the "Out of memory" case. To do this we run the line coverage probe again, but this time we add the demo UAL, so both the demo and coverage probes are applied. (One can use many different probes at the same time!)

  1. Run demo.exe with both coverage and demo probes:
    aprobe -u coverage -u demo demo.exe
  2. Format the results:
    apformat demo
Now we see that lines 31 and 33 through 38 were not executed (but lines 26 and 27 were). That sure was easier than trying to construct a case where the test really ran out of memory in order to test this execution path.

Aprobe provides a mechanism to merge these results to get a combined report: see $APROBE/examples/learn/test_coverage.

Of course, custom probes can do much more than this demo shows. If you want to get an idea of what they can do, we suggest that you try the examples in the directories under $APROBE/examples/.

For other information, including white papers, visit www.aprobe.com or contact sales@ocsystems.com.

[Up to Aprobe Demos]