Providing Counter Data Using Version 2.0

Modern performance data providers use a manifest to define the counter data and use performance counter provider APIs to manage data within the context of the provider. Providers implemented using a manifest and performance counter provider APIs are often called V2 providers. Windows supports user-mode V2 providers on Windows Vista or later and kernel-mode V2 providers on Windows 7 or later.

This page describes user-mode V2 providers. For information about kernel-mode V2 providers, see Kernel Mode Performance Monitoring.

At runtime, V2 providers work as follows:

• The provider process registers itself with the Windows Performance Counter system by calling PerfStartProvider and PerfSetCounterSetInfo. The provider optionally provides a callback function that will be notified about consumer requests.
• The provider process adds or removes instances as appropriate using PerfCreateInstance and PerfDeleteInstance. The provider updates counter values when they change using PerfSet*** APIs.
• A consumer makes a request for data from a counterset. The system verifies that the caller has permissions to collect the data. The system then uses a worker thread running in the provider process to handle the request, invoking the provider's callback function if appropriate. The worker thread copies the collected data into a system-managed buffer, and the system then returns the data to the consumer.

Steps to creating a provider

1. Write a manifest that defines the counter data that your provider will provide. For details on writing the manifest, see Performance Counters Schema.

2. Use CTRPP to generate the template code that you include in your provider. The template code includes the structures that define the counter sets, the CounterInitialize and CounterCleanup functions, and the resource strings.

   Your provider must call the CounterInitialize and CounterCleanup functions. The CounterInitialize calls the PerfStartProvider function to register the provider and also calls the PerfSetCounterSetInfo function to initialize the counter set. The CounterCleanup calls the PerfStopProvider function to remove the provider's registration.

3. Include the template code from the previous step in your project and complete your provider.

   To complete the provider, you need to call the PerfCreateInstance function for each instance of the counter set that you provide.

   To set the counter values, call one of the following functions:

   • PerfSetULongCounterValue
   • PerfSetULongLongCounterValue
   • PerfSetCounterRefValue

   The benefit of using PerfSetCounterRefValue is that you do not have to make a function call to set or update the counter value, you simply update your local counter variable (the variable to which the reference points) and Performance Counters uses the pointer to access the counter value.

   If you do not use PerfSetCounterRefValue, you can use the following functions to increment or decrement the counter value:

   • PerfDecrementULongCounterValue
   • PerfDecrementULongLongCounterValue
   • PerfIncrementULongCounterValue
   • PerfIncrementULongLongCounterValue

   Before the provider exits, it must call the PerfDeleteInstance for each counter set instance that it created.

   If you specified the callback attribute in the provider element in your manifest or used the -NotificationCallback argument when calling CTRPP, you must implement the ControlCallback callback function. You pass the callback function to CounterInitialize.

   If you used the -MemoryRoutines when calling CTRPP, you must implement the AllocateMemory and FreeMemory callback functions. You pass the callback functions to CounterInitialize.

4. When installing your provider, use the LodCtr tool to write the name of the binary file that contains the localized resource strings and resource IDs to the registry. For details on using LodCtr, see Performance Counters Schema.

5. When uninstalling your provider, use the UnlodCtr tool to remove your provider's information from the registry.