Using the Registry Functions to Consume Counter Data
Use the registry functions to collect performance data from the special
HKEY_PERFORMANCE_DATA registry key.
Performance data is not actually stored in the registry. Calling the registry functions causes the system to collect the data from the appropriate performance data provider.
You should not normally use the registry functions to consume counter data. Instead, you should use the Performance Data Helper (PDH) functions. The PDH functions are easier to use and avoid many performance and reliability problems that can occur through incorrect use of the registry functions.
You cannot use the registry functions if you are writing Windows OneCore apps. Instead, use PerfLib V2 Consumer functions.
The registry functions are the low-level API for collecting data from V1 providers. The registry functions also support collecting data from V2 providers via a translation layer that calls into the V2 Consumer functions.
To obtain performance data from the local system, call the RegQueryValueEx function. Use
HKEY_PERFORMANCE_DATA as the key. The first call opens the key. You do not need to explicitly open the key first.
To obtain performance data from a remote system, call the RegConnectRegistry function. Use the computer name of the remote system and use
HKEY_PERFORMANCE_DATA as the key. This call retrieves a key representing the performance data for the remote system. Use this key rather than
HKEY_PERFORMANCE_DATA key to retrieve the data.
Be sure to use the RegCloseKey function to close the handle to the key when you are finished obtaining the performance data. This is important for both the local and remote cases:
RegCloseKey(HKEY_PERFORMANCE_DATA)does not actually close a registry handle, but it clears all cached data and frees the loaded performance DLLs.
RegCloseKey(hkeyRemotePerformanceData)closes the handle to the remote machine's registry.
Do not call
You use the
lpValueName parameter of the RegQueryValueEx function to indicate the information to retrieve. The following table lists the values you can specify for
lpValueName. Note that the value strings are not case-sensitive.
||Retrieves performance data for all performance objects registered on the computer except for those included in the
||Windows Vista and later: Retrieves performance data for all V1 performance objects registered on the computer except for those included in the
||Retrieves performance data for one or more performance objects. Specify the decimal index associated with each object that you want to retrieve in a space-separated list. For example, if you want to retrieve System and Memory objects and you have determined that the indexes of the corresponding name strings are 2 and 4, specify the string
||Retrieves name strings for the specified language identifier, e.g. English for
||Retrieves help strings for the specified language identifier, e.g. English for
||Deprecated: Retrieves performance data for object types whose data is expensive to collect in terms of processor time or memory usage. This collection may take several minutes on a heavily-loaded machine. You should perform the collection on a worker thread if your application needs to respond to the user during this data collection.|
||Windows 10 20H1 and later: Retrieves metadata for all performance objects registered on the computer except for those included in the
||Windows 10 20H1 and later: Retrieves metadata for all V1 performance objects registered on the computer except for those included in the
||Windows 10 20H1 and later: Retrieves metadata for costly performance objects.|
||Windows 10 20H1 and later: Retrieves metadata for costly V1 performance objects.|
For details on the format of the performance data that the registry returns, see Performance Data Format.
For an example that gets the names and descriptions of the registered counters on the computer, see Retrieving Counter Names and Help Text.
For an example that accesses the components of the performance data, see Displaying Object, Instance, and Counter Names.
Windows 10 20H1 adds support for metadata-only collection operations. These operations are intended for use when making a list of the performance objects and counters that are available on a machine.
- Metadata-only collection can be faster than the corresponding full-data collection because it can skip collecting instance data from objects that support metadata-only collection.
- Metadata-only collection uses less memory than the corresponding full-data collection because it does not need space to return instance data from objects that support metadata-only collection.
- Metadata-only collection is more complete than the corresponding full-data collection because it returns the list of available counters even if there are no instances of objects that support metadata-only collection.
Appropriate use of metadata-only collection is especially important when collecting data from servers with many processes or threads. A normal
Global collection must collect and return information on each process and thread on the system, while
MetadataGlobal collection does not need to collect process or thread information.
The Performance Data Helper (PDH) functions automatically use metadata-only collection when determining the set of performance objects available on a machine.
Operating system support for metadata-only operations is indicated by a nonzero value in the
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\Supports Metadata registry value. If this value is not present or is set to
0, use a full-data collection (e.g.
Global) instead of a metadata-only collection (e.g.
Not all performance objects support metadata-only collection. When you request a
MetadataGlobal collection, Windows will check each performance object for metadata-only support (indicated by a nonzero value in the
HKLM\SYSTEM\CurrentControlSet\Services\<ServiceName>\Performance\Collect Supports Metadata registry value). If the performance object does not support metadata-only collection, Windows will perform a normal data collection from the object. If the performance object does support metadata-only collection, Windows will perform a metadata-only collection from the object. The data returned to you for a metadata-only query will then contain
PERF_OBJECT_TYPE blocks from both full-data and metadata-only collection. The
PERF_OBJECT_TYPE blocks may contain or omit instance information, depending on whether the block was collected from a provider that does or does not support metadata-only queries.
The data returned from a metadata-only collection is the same as the data from a normal collection except:
NumInstancesfield of the
PERF_OBJECT_TYPEstruct will be either
PERF_METADATA_MULTIPLE_INSTANCES(indicating that the object supports 0 or more named instances) or
PERF_METADATA_NO_INSTANCES(indicating that the object always has 1 unnamed instance).
- There will be no
PERF_INSTANCE_DEFINITIONblocks after the
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib registry key supports several
DWORD values related to performance counter collection.
These should usually be unset for default behavior, but may be configured by an administrator as needed for specific scenarios.
Configuration Flags: Default is 0. May be set to a combination of the following flags to enable special behavior:
0x01: Do not test plugins for data buffer alignment errors. By default, the system validates the buffer alignment of plugins.
0x02: Do not automatically disable plugins. By default, the system disables plugins that crash or exhibit incorrect behavior.
0x04: Do not validate plugin buffer integrity. By default, the system checks for plugin buffer overruns.
0x08: Do not check for plugin timeouts. By default, the system checks for plugin hangs.
Disable Performance Counters: Default is 0. If set to 1, collection of V1 performance counters will be disabled for the system.
ExtCounterTestLevel: Default is 4. Controls how much validation the system performs to guard against incorrect plugin behavior. See