Debugging Your Performance Counter DLL

[Previous] [Next]

As you can see, the data block produced by your DLL's Collect function is complex, and it usually takes most developers quite some time to completely debug it. To help you out, Microsoft has added some support in the operating system to analyze Collect function behavior. If the system detects any problem, it will generate an entry into the system's Application event log. Figure 7-11 provides an example.

Figure 7-11. A performance DLL error reported to the Application Log

By default, the system does not perform this additional checking because it adversely affects the speed of retrieving performance counter data. To turn on this checking, go to the subkey in the registry that is listed here.

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

Under this key, add a REG_DWORD value named ExtCounterTestLevel and set it to one of the values listed in Table 7-4.

Table 7-4. ExtCounterTestLevel values that specify levels of performance data testing

Value	Description
1	The system should check all object and counter lengths for consistency.
2	The system should check for buffer overflows and guard pages.
3	The system should not perform any checking.
4	Don't even allocate a guard page. This is the default if this registry value does not exist.

Whenever the system detects a problem with performance data, it writes an entry to the system's Application Log. You can control the nature of this entry: under the same registry subkey, create a REG_DWORD value named EventLogLevel and set it to one of the values listed in Table 7-5.

Table 7-5. EventLogLevel values that specify what events should be recorded in the event log

Value	Description	Event ID Range
0	The system should never report anything to the event log.	(not applicable)
1	The system should report user-related events in the event log.	1000-1015, 1017-1020
2	The system should report warnings and errors in the event log.	1000-1015, 1017-1020, 1016, 2000-2003
3	The system should report information events as well as warnings and errors in the event log.	1000-1015, 1017-1020, 1016, 2000-2002, 3000-3001

Table 7-6 shows the types of events that can be placed in the event log.

Table 7-6. Events that indicate performance data problems

Event ID	Description
1000	Access to performance data was denied to <username> as attempted from <calling module name>
1001	The buffer size returned by a collect procedure in Extensible Counter DLL "<dll name>" for the "<service name>" service was larger than the space available. Performance data returned by counter DLL will not be returned in Perf Data Block. Overflow size is data DWORD 0.
1002	A Guard Page was modified by a collect procedure in Extensible Counter DLL "<dll name>" for the "<service name>" service. Performance data returned by counter DLL will not be returned in Perf Data Block.
1003	The object length of an object returned by Extensible Counter DLL "<dll name>" for the "<service name>" service was not correct. The sum of the object lengths returned did not match the size of the buffer returned. Performance data returned by counter DLL will not be returned in Perf Data Block. Count of objects returned is data DWORD 0.
1004	The instance length of an object returned by Extensible Counter DLL "<dll name>" for the "<service name>" service was incorrect. The sum of the instance lengths plus the object definition structures did not match the size of the object. Performance data returned by counter DLL will not be returned in Perf Data Block. The object title index of the bad object is data DWORD 0.
1005	Unable to locate the open procedure "<open proc name>" in DLL "<dll name>" for the "<service name>" service. Performance data for this service will not be available. Error Status is data DWORD 0.
1006	Unable to locate the collect procedure "<collect proc name>" in DLL "<dll name>" for the "<service name>" service. Performance data for this service will not be available. Error Status is data DWORD 0.
1007	Unable to locate the close procedure "<close proc name>" in DLL "<dll name>" for the "<service name>" service. Performance data for this service will not be available. Error Status is data DWORD 0.
1008	The Open Procedure for service "<service name>" in DLL "<dll name>" failed. Performance data for this service will not be available. Status code returned is DWORD 0.
1009	The Open Procedure for service "<service name>" in DLL "<dll name>" generated an exception. Performance data for this service will not be available. Exception code returned is DWORD 0.
1010	The Collect Procedure for the "<service name>" service in DLL "<dll name>" generated an exception or returned an invalid status. Performance data returned by counter DLL will not be returned in Perf Data Block. Exception or status code returned is DWORD 0.
1011	The library file "<dll name>" specified for the "<service name>" service could not be opened. Performance data for this service will not be available. Status code is data DWORD 0.
1012	The system reported an idle process time that was less than the last time reported. The data shows the current time and the last reported time for the system's idle process.
1013	The collect procedure in Extensible Counter DLL "<dll name>" for the "<service name>" service returned a buffer that was larger than the space allocated and may have corrupted the application's heap. This DLL should be disabled or removed from the system until the problem has been corrected to prevent further corruption. The application accessing this performance data should be restarted. The Performance data returned by counter DLL will not be returned in Perf Data Block. Overflow size is data DWORD 0.
1014	An error occurred while trying to collect data from the Server Object. The Error code returned by the function is DWORD 0. The Status returned in the IO Status Block is DWORD 1. The Information field of the IO Status Block is DWORD 2.
1015	The timeout waiting for the performance data collection function "<function name>" in the "<dll name>" Library to finish has expired. There may be a problem with this extensible counter or the service it is collecting data from or the system may have been very busy when this call was attempted.
1016	The data buffer created for the "<service name>" service in the "<dll name>" library is not aligned on an 8-byte boundary. This may cause problems for applications that are trying to read the performance data buffer. Contact the manufacturer of this library or service to have this problem corrected or to get a newer version of this library.
1017	Performance counter data collection from the "<service name>" service has been disabled due to one or more errors generated by the performance counter library for that service. The error(s) that forced this action have been written to the application event log. The error(s) should be corrected before the performance counters for this service are enabled again.
1018	Performance counter data collection from the "<service name>" service has been disabled for this session due to one or more errors generated by the performance counter library for that service. The error(s) that forced this action have been written to the application event log.
1019	A definition field in an object returned by Extensible Counter DLL "<dll name>" for the "<service name>" service was incorrect. The sum of the definitions block lengths in the object definition structures did not match the size specified in the object definition header. Performance data returned by this counter DLL will be not be returned in Perf Data Block. The object title index of the bad object is data DWORD 0.
1020	The size of the buffer used is greater than that passed to the collect function of the "<dll name>" Extensible Counter DLL for the "<service name>" service. The size of the buffer passed in is data DWORD 0 and the size returned is data DWORD 1.
2000	The pointer returned did not match the buffer length returned by the Collect procedure for the "<service name>" service in Extensible Counter DLL "<dll name>". The Length will be adjusted to match and the performance data will appear in the Perf Data Block. The returned length is data DWORD 0, the new length is data DWORD 1.
2001	The "<service name>" service does not have a Performance subkey or the key could not be opened. No performance counters will be collected for this service. The Win32 error code is returned in the data.
2002	The open procedure for service "<service name>" in DLL "<dll name>" has taken longer than the established wait time to complete. There may be a problem with this extensible counter or the service it is collecting data from or the system may have been very busy when this call was attempted.
2003	The configuration information of the performance library "<dll name>" for the "<service name>" service does not match the trusted performance library information stored in the registry. The functions in this library will not be treated as trusted.
3000	Open procedure for service "<service name>" in DLL "<dll name>" was called and returned successfully.
3001	An updated performance counter library file has been detected. The performance counters for the "<dll name>" have been enabled.

You'll notice that some of the events listed in Table 7-6 have to do with timing. For example, if the DLL's Open function takes too long to return, the system assumes that something is wrong with the performance-counter DLL and generates an event with ID 2002. Set the OpenProcedureWaitTime value in the registry to let the system know how long it should wait before reporting this event. This value is listed under the same registry subkey as the other two values (ExtCounterTestLevel and EventLogLevel). Furthermore, this value is also a REG_DWORD value that you set to the number of milliseconds that will be good enough for all Open functions.

NOTE

---

This value affects only how long the system should wait to generate the event log entry. Setting a timeout does not force the system to abandon the Open function and do something else. If the Open function does not return, the application requesting the performance data stops executing.

Whereas a single registry value is used for all Open functions, each performance-counter DLL can set a unique Collect function timeout value. To set a time limit (in milliseconds) for your DLL's Collect function, create a REG_DWORD registry value named Collect Timeout. (The space between the words is mandatory.) This value must be placed in the following subkey:

 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Performance 

Again, the ServiceName portion of this subkey is the part that uniquely identifies your service or application performance data. If your DLL's Collect function doesn't return in the specified number of milliseconds, an event ID 1015 is added to the system's Application Log.