Welcome to the Aprobe-Perfmon example.
By now, you should have a solid understanding of Aprobe - you've run the demo and gone through some of the examples. If you haven't done that yet, what are you waiting for? We invite you to start up Aprobe, open the demo, and then follow the step-by-step instructions.
Since probes are written in C, they can use any Windows API functions or interfaces to assist in analyzing your applications.
This example shows how to interface to the Windows NT Performance Monitor - from here on we'll refer to it as "perfmon"(1).
Perfmon is a very powerful but overlooked tool sitting on your machine. It provides a display of things like CPU usage, memory usage and disk access. Furthermore, it can have user-defined performance counters added to it so you can display information in realtime from your applications.
Normally adding counters is pretty tricky and will require modifications to your code. In this example, we use Aprobe to add modifications with probes leaving your code untouched.
To add these keys to the registry, use the registry key installation application included with Aprobe and found in Aprobe\bin. Here's what to do:
This actually installs support for both the Perfmon counters and the Event Log interface, both described in Appendix E of the User's Guide.
With this complete, you're ready to proceed.
For this example we will work at the command prompt, in the directory
C:"\Program Files\OC Systems\Aprobe\Examples\Advanced\Perfmon"
(Note: If you installed Aprobe someplace else, then "cd" to there instead.)
If you're not using the Aprobe-aware command prompt (from your menu), you must now setup the PATH to both Aprobe and your Visual C++ compiler by typing:
..\..\..\setup
To start the Performance Monitor, just type perfmon at the Command Prompt. You can also find it on the Start menu ... by default under Programs / Administrative Tools.
The first thing to do with perfmon is to add the counters to be displayed on the Performance Monitor chart. Click on the "+" button on the toolbar (or select the Edit - Add to Chart menu option) to bring up the Add to Chart dialog.
From the dialog, click Add to add the currently selected Counter (this is the %Processor Time). A red line will appear on the chart showing the current CPU usage. Later we will add the Aprobe counter used in this example.
Once everything is setup, you're ready to run the example.
This example uses the same application program as the C++ Demo, a simple dialog-based application that allows you to choose between bubble sort(2) and quicksort(3).
Because this application, ..\..\Target\Cpp_Demo\Demo.exe is rather large, we just deliver the source code, and you'll have to build it first before proceeding (unless you already built it when you ran the demo). To do this:
pushd ..\..\Target\Cpp_Demo nmake popd
Leave the command line window open, since this whole demo uses it.
To verify that it was built and runs properly, type:
..\..\Target\Cpp_Demo\Demo.exe
and make sure the sorting dialog appears.
In the perfmon example directory you should see the following three APC files:
perfmon_demo1.apc perfmon_demo2.apc perfmon_demo3.apc
Before we look at the APC code, let's have a look at them in action. Compile the first APC file and run the demo application:
apc perfmon_demo1.apc ap_perfmon.lib aprobe -u perfmon_demo1.dll ..\..\Target\Cpp_Demo\Demo.exe
The example executable will open; arrange your screen so you can see it and the Performance Monitor tool. Now add the Aprobe counter used for the first part of the demo: Select 'Aprobe Counters' from the "Object" combo-box and 'Aprobe Counter 00 (Raw)' from the list of counters. Change the scale to '0.0001' and click 'Add'. Then do the same for 'Aprobe Counter 04 (Rate)'. Click Done to dismiss the dialog.
Note: If you couldn't find the Aprobe counters. You haven't installed them properly. Remember, you must have administrative privileges to install the counters into the registry; you do not need these privileges to use the counters once they are installed. See Installing the Perfmon Counters above.
This will show two things: First, the current CPU usage (the red line) and second, a counter showing the number of comparisons done while the sort is in progress (the green line), and the number of comparisions per second (the blue line). The first performance counter is generated by the system; the second and third are done using Aprobe. Play around with the demo dialog so that you can see the effect of the number of items sorted on both the CPU and the number of comparisons counters. Note that QuickSort has much lower numbers of comparisons for the same number of items than BubbleSort. Click the Done button when you're finished.
If you run Demo.exe on its own, it will run the same. You'll still see CPU spikes but the Aprobe counters will not change which proves Aprobe and not the demo is updating the counters.
Obviously Aprobe can still log data as normal while it is changing perfmon counters. Run apformat to verify that you see the expected output:
apformat Demo
The output from apformat should be something like:
SortClass::BubbleSort(void) made 809100 comparisons to sort 900 items SortClass::QuickSort(void) made 8257 comparisons to sort 900 items SortClass::QuickSort(void) made 117177 comparisons to sort 9000 items
Let's take a look to see how Aprobe accomplished this:
By now you should be familar with APC files. This one adds very few calls to update the perfmon counters. Let's take a look at the changes:
And that's all there is to adding perfmon counters to your probes. When you understand this, head to the next demo where we extend the data logged so that we can track the times spent in the routines.
Often you will be using Aprobe and the perfmon tool to get some sort of performance information about your application. Timing information is obviously very useful in this regard. Aprobe makes it very easy to get and display times and durations.
In perfmon_demo2.apc we extend the APC file to log the time that our sort routines start and end. Here are the changes from the previous file:
As usual, to run this first compile the APC file, run it under Aprobe and then use apformat to look at our data:
apc perfmon_demo2.apc ap_perfmon.lib aprobe -u perfmon_demo2.dll ..\..\Target\Cpp_Demo\Demo.exe apformat demo
You should see output similar to:
SortClass::BubbleSort(void) made 809100 comparisons to sort 900 items Entered at: Thu Jun 03 13:03:51.783737600 1999 Finished at: Thu Jun 03 13:03:56.200088000 1999 Duration: 00:00:04.416350400 SortClass::QuickSort(void) made 8257 comparisons to sort 900 items Entered at: Thu Jun 03 13:03:56.680779200 1999 Finished at: Thu Jun 03 13:03:56.720836800 1999 Duration: 00:00:00.040057600 SortClass::QuickSort(void) made 117177 comparisons to sort 9000 items Entered at: Thu Jun 03 13:03:59.805272000 1999 Finished at: Thu Jun 03 13:04:00.336035200 1999 Duration: 00:00:00.530763200
Obviously getting at timing information is something you will often want to do with Aprobe so it is good to know it is so simple. The final demo will show how to add another counter.
Finally it's time for you to do some work. We want to extend the demo to add another performance counter to show the efficiency of the sort - the ratio of a number of comparisons to the number of items sorted.
The following steps give some hints about how this can be done. If you get stuck, or just want to cheat and peek at the solution, look at perfmon_demo3.apc:
Before running the demo with your new probe, add the counter to the perfmon chart by bringing up the Add to Chart dialog, selecting the Aprobe Counters object again and adding Aprobe Counter 08 (Fraction) to the list. You will notice that there is no counter 09 listed. That is because the fraction counters work together in pairs. Perfmon automatically divides them and displays the result. Then compile and run your new probe as normal:
apc new probe filename ap_perfmon.lib aprobe -u new probe DLL name ..\..\Target\Cpp_Demo\Demo.exe
If all is well, you should see your efficiency line in blue on the perfmon chart (note that the BubbleSort is so inefficient, you won't see it go above zero unless you lower the number of items substantially or change the scale).
That's it for the perfmon demo. Hopefully you now understand how Aprobe can work with other tools on Windows NT to really assist in capturing the data you need.
The Windows NT Performance Monitor tool allows you to investigate system and application performance in realtime. It has an extensible interface which you can access through Aprobe to add your own counters, driven by probes that you write!
A very simple algorithm for sorting an array of items. Each item is compared to it's neighbor to see if it should be swapped. This is repeated until the list is sorted. It gets it's name from the fact that items "bubble up" the list to their correct location on each pass of the list.
This is a recursive algorithm which divides a list in half and then sorts that.