The Architecture of Performance Objects and Counters

[Previous] [Next]

To expose your own performance information, you must make several modifications to the registry. You can think of these modifications as falling into two groups. The first set of modifications tells the system that your counters exist; the second set of modifications tells the system how to get the performance information for your counters. As shown in Figure 7-5, the initial modifications are performed under the following registry subkey:

 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib 

Figure 7-5. Settings in the registry that indicate your counters' existence

Under the Perflib subkey is another subkey, 009, which corresponds with the LANG_ENGLISH symbol defined in WinNT.h. Under the 009 subkey are two values: Counter and Help. Both of these values are of the REG_MULTI_SZ type. You can examine or edit these two registry values with the RegEdt32.exe registry editor utility that comes with Windows. Unfortunately, you cannot use the RegEdit.exe tool (which also ships with Windows) because this tool has an internal limitation that prevents it from displaying or editing values larger than 32 KB.

The Counter value contains a set of strings defining the objects and counters that the system is to be made aware of. The following list shows a small sampling of the strings in this value:

 2 System 4 Memory 6 % Processor Time 10 File Read Operations/sec 12 File Write Operations/sec 14 File Control Operations/sec 16 File Read Bytes/sec 18 File Write Bytes/sec 

The Help value contains a set of strings that explain the meaning of a performance object or counter. Here is a small sampling of the Help value:

 3 The System performance object consists of counters that apply to more than one instance of a component processors on the computer.1 5 The Memory performance object consists of counters that describe the  behavior of physical and virtual memory on the computer. Physical memory is the amount of random access memory on the computer. Virtual memory consists of the space in physical memory and on disk. Many of the memory counters monitor paging, which is the movement of pages of code and data between disk and physical memory. Excessive paging, a symptom of a memory shortage, can cause delays which interfere with all system processes. 7 % Processor Time is the percentage of time that the processor is executing a non-Idle thread. This counter was designed as a primary indicator of processor activity. It is calculated by measuring the time that the processor spends executing the thread of the Idle process in  each sample interval, and subtracting that value from 100%. (Each  processor has an Idle thread which consumes cycles when no other threads  are ready to run). It can be viewed as the percentage of the sample  interval spent doing useful work. This counter displays the average  percentage of busy time observed during the sample interval. It is  calculated by monitoring the time the service was inactive, and then  subtracting that value from 100%. 9 % Total DPC Time is the average percentage of time that all processors  spent receiving and servicing deferred procedure calls (DPCs). (DPCs are  interrupts that run at a lower priority than the standard interrupts). It  is the sum of Processor: % DPC Time for all processors on the computer,  divided by the number of processors. System: % Total DPC Time is a  component of System: % Total Privileged Time because DPCs are executed in  privileged mode. DPCs are counted separately and are not a component of  the interrupt count. This counter displays the average busy time as a  percentage of the sample time. 11 File Read Operations/sec is the combined rate of file system read  requests to all devices on the computer, including requests to read from  the file system cache. It is measured in numbers of reads. This counter  displays the difference between the values observed in the last two  samples, divided by the duration of the sample interval. 13 File Write Operations/sec is the combined rate of the file system write  requests to all devices on the computer, including requests to write to  data in the file system cache. It is measured in numbers of writes. This  counter displays the difference between the values observed in the last  two samples, divided by the duration of the sample interval. 15 File Control Operations/sec is the combined rate of file system  operations that are neither reads nor writes, such as file system control  requests and requests for information about device characteristics or  status. This is the inverse of System: File Data Operations/sec and is  measured in number of operations perf second. This counter displays the  difference between the values observed in the last two samples, divided  by the duration of the sample interval. 17 File Read Bytes/sec is the overall rate at which bytes are read to  satisfy file system read requests to all devices on the computer,  including reads from the file system cache. It is measured in number of  bytes per second. This counter displays the difference between the values  observed in the last two samples, divided by the duration of the sample interval. 19 File Write Bytes/sec is the overall rate at which bytes are written to  satisfy file system write requests to all devices on the computer,  including writes to the file system cache. It is measured in number of  bytes per second. This counter displays the difference between the values  observed in the last two samples, divided by the duration of the sample  interval. 

1. Unfortunately, this Help text doesn't make any sense. I pointed out this "bug" to Microsoft, but they decided not to correct it because Windows 2000 was so close to shipping.

You'll notice that the Counter value strings are in pairs. Each pair consists of an even number and a short string. The Help value strings are also in pairs, but the numbers are odd. The system uses the Counter value to determine which performance objects and counters are available on the system. The Help value identifies each object's or counter's explanation text; the Help text's numerical value is always one greater than the object's or counter's numerical value. As I mentioned earlier, the System Monitor control currently has no way of showing the Help text for performance objects. This means that you'll never see the Help text associated with the numbers 3 and 5, for example.

To add your own performance objects and counters to the system, you must append your objects, counters, and Help string pairs to these two registry values. Referring back to Figure 7-5, two of the values you see under the Perflib subkey are Last Counter and Last Help. These two values tell you the highest number used in the Counter and Help values, respectively. Since, in my registry, Last Counter has a value of 2276, any new objects or counters added to the system start at 2278. Similarly, any new Help text would start at 2279. Microsoft reserves a certain set of numbers for the system itself. The Base Index value (1847) indicates the highest number that Microsoft has reserved for the system's own objects and counters. Objects and counters that you add must be above this number.

Now we'll turn our attention to the other part of the registry. To expose your own performance objects, instances, and counters, you must create a DLL that is responsible for returning your performance information. Once the DLL is created, you must tell the system about it by making some more modifications to the registry. As shown in Figure 7-6, however, these modifications are made in a different part of the registry:

 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HWInputMon\ Performance 

The HWInputMon portion of this subkey uniquely identifies my performance data. You will, of course, replace this portion with a name that uniquely identifies your performance data.

Figure 7-6. Settings in the registry that indicate how the system can query performance information from a DLL

Within this subkey are several data values. The most important value, Library, specifies the pathname of the DLL that knows how to return your performance information. This DLL must export three functions: an open function, a collect function, and a close function. You can choose any names for these functions that you desire, but the names must be specified using the Open, Collect, and Close values in the registry.

When performance information is being requested, the system will load your DLL and immediately call its Open function. Your Open function should look like this:

 DWORD __declspec(dllexport) WINAPI Open(PWSTR) {    // Note: The parameter is always ignored    // Initialize the DLL    return(ERROR_SUCCESS); } 

This gives your DLL the opportunity to initialize itself. Once initialized, the system will periodically make calls to your Collect function. This function is responsible for initializing a memory buffer that contains all the performance information you want to return. I'll discuss the prototype of the Collect function later in "Collecting Performance Data," and provide details about its implementation.

When the system decides to unload your DLL, it calls the Close function, giving you the opportunity to perform any necessary cleanup. The Close function should look like this:

 DWORD __declspec(dllexport) WINAPI Close() {    // Clean up the DLL    return(ERROR_SUCCESS); } 

The four registry values discussed so far are the only ones required by the system. However, it is frequently useful to have some additional registry values, as shown in Figure 7-6. As mentioned earlier, when you add new performance objects and counters to the system, you must append your performance object and counter strings to the registry. These new strings have to begin with unique numbers. It is absolutely essential that your performance DLL remember what object and counter numbers it has been assigned. The easiest place to store this information is in the Performance registry subkey. Figure 7-6 shows that I have added the First Counter, Last Counter, First Help, and Last Help values to the registry for just this purpose. When my DLL loads, I open the registry, extract these values, and save them for reference by my Collect function. It is necessary to know your object and counter numbers because when the system calls the Collect function, it passes these numbers to identify which performance information should be returned.

Now you're probably wondering into which process your DLL gets loaded. There are two scenarios, depending on whether your performance information is being queried locally or remotely. When the System Monitor control is used to query performance information from the local machine, the system loads your DLL into the address space of the process that created the System Monitor control. (See Figure 7-7.) Because the DLL is running in another process's address space, it is critically important that you thoroughly test your code and make sure that it is very robust. If your code contains any infinite loops, calls ExitProcess, or deadlocks waiting for some thread synchronization object, you'll be adversely affecting the process.

Figure 7-7. Local performance monitoring

Microsoft designed a robust System Monitor control to withstand a lot of "passive-aggressive" behavior. For example, the System Monitor control spawns a separate thread when calling into a DLL's Collect function; if that thread doesn't return in a fixed amount of time, the System Monitor control kills it and continues running. The System Monitor control also wraps the call to your DLL functions inside a structured exception-handling frame to catch any access violations, divisions by 0, or other hard errors that your code might generate.

A slightly different scenario exists when your performance information is being queried by a remote computer, as shown in Figure 7-8. In this scenario, the remote computer is actually talking to an RPC server contained inside WinLogon.exe. When WinLogon detects a request for performance information, it loads your DLL into WinLogon's address space. The information that you return from the Collect function is then marshaled to the machine making the request. For the System Monitor control, this remote communication occurs transparently.

Figure 7-8. Remote performance monitoring

Be aware that the ramifications of loading a performance DLL into WinLogon's address space are much more critical than loading a DLL into an application's address space. If the DLL calls the ExitProcess function now, WinLogon will terminate, which will, in turn, crash the entire operating system. Again, I cannot stress enough how important it is to test the code residing in your performance DLL.