Tcl Windows API extension

This package provides procedures related to retrieving Windows performance counters. This documentation is reference material for related commands. For more introductory material and a guide with examples, see the Performance Monitoring chapter in the Tcl on Windows online book.

Performance Objects

To get a list of performance objects on a system, call pdh_enumerate_objects. Commands pdh_enumerate_object_counters, pdh_enumerate_object_instances and pdh_enumerate_object_items return the counters and instances for a particular performance object.

Counter Paths

Similar to files in a file system, performance counters are identified by a counter path. A counter path is of the form

\\Computer\PerfObject(ParentInstance/ObjectInstance#InstanceIndex)\Counter

Not all components in a counter path need to be specified. See Windows SDK documentation for a detailed description and examples. Note that \ and / are not interchangeable in a counter path

To construct a counter path, call pdh_counter_path. The break down a counter path into its components, call pdh_parse_counter_path.

Retrieving Counter Values

To retrieve values for a counter, use the following sequence of commands

pdh_query_open	Opens a query object to which counters can be added.
pdh_counter_path	Constructs a counter path for the performance object and instance of interest. Call for each counter of interest.
pdh_add_counter	Adds a counter (specified by its counter path as returned in the previous step) to a query and returns a handle to it. Call for each counter of interest.
pdh_query_refresh	Updates all counters in the query to their current values. For rate based counters, this must be called at least twice before retrieving the value of a counter.
pdh_get_scalar	Returns the scalar value of a counter as updated in the last call to pdh_query_refresh.
pdh_get_array	Returns a counter that is an array of values (for example, one for each process) as updated in the last call call to pdh_query_refresh.
pdh_query_get	Returns values for multiple counters from a query. Internally does the equivalent of pdh_query_refresh.
pdh_query_close	Closes a query. This should be called to release resources associated with a query once the contained counters are no longer required.

The pdh_system_performance_query is a wrapper around pdh_query_open that includes some commonly used system counters.

set queryh [pdh_system_performance_query processor_utilization memory_free_kb]
proc print_counters {queryh} {
    pdh_query_refresh $queryh
    puts [pdh_query_get $queryh]
    after 1000 [info level 0]
}
print_counters $queryh
vwait forever

Commands

pdh_add_counter HPERF CTRPATH ?options?

Adds a counter specified by its path CTRPATH to a performance query. HPERF is a query handle previously returned by pdh_query_open. CTRPATH is a counter path normally constructed through pdh_counter_path. Subsequent calls to pdh_query_refresh for that query will update the counter.

The command returns a handle to the counter which can then be passed to pdh_get_scalar or pdh_get_array to retrieve its value. Alternatively, the pdh_query_get command can be used to get values of multiple counters from a query.

The counter is automatically released when the query is closed. However, if a counter is no longer required while the other counters in the query are still in use, it can be removed from the query by calling pdh_remove_counter.

The following options may be specified with the command. They impact how values from the counter are returned from the pdh_query_get command.

-array BOOLEAN	If true ,the counter is treated as an array of values. If false (default), it will be returned as a scalar.
-format FORMAT	Specifies how the counter value should be formatted. FORMAT may be on of long, large or double for a 32-bit integer, a 64-bit integer or a floating point double.
-name NAME	Specifies the mnemonic name by which the counter will be identified when multiple counter values are retrieved with pdh_query_get. If unspecified, defaults to the full counter path CTRPATH.
-scale SCALE	By default, each counter has a default scaling factor. If SCALE is none, the counter value is returned without the default scaling. If SCALE is x1000, the returned value is scaled up by a factor of 1000. If SCALE is nocap100, the counter value is not capped at 100 as is the scale for some counters like processor utilization.

pdh_counter_path PERFOBJ CTRNAME ?options?

Returns a path to a performance counter that can then be passed to pdh_add_counter. PERFOBJ should be the name of the performance object, such as TCPv4. CTRNAME should be the name of the performance counter in the object, such as Connection Failures. The following additional options may be passed:

-instance INSTANCE	When there are many instances of a performance object, as is true for the Process object for example, this option allows specification of a particular instance by specifying its name as INSTANCE. Many performance objects allow INSTANCE to be specified as * to indicate counters for all instances are to be returned.
-instanceindex INSTANCEINDEX	When there is more than one instance of a performance object with the same name, this option allows selection of a particular one by specifying its numeric instance index.
-localized BOOLEAN	Performance object and counter names are localized based on the system languages. Using Process as the object name on a French localized system will result in a failure. By default the command assumes the passed names are in English and localizes them for the local system. If -localized is passed as true, the command assumes that the names being passed are already appropriately localized.
-parent PARENTINSTANCE	Some performance objects, like Thread, are contained within another parent object, Process in the case of Thread. In such cases PARENTINSTANCE specifies the context for the target object.

See Windows SDK documentation for more details on counter path syntax and components.

pdh_enumerate_objects ?options?

Returns a list of the names of the performance objects on a system. The following options may be specified:

-detail DETAILLEVEL	Controls which detail levels are to be returned. DETAILLEVEL may be one of novice, advanced, expert and wizard (default) which return performance objects at an increasing level of detail.
-refresh	The list of performance objects is returned from a cache. Performance objects may be added by any application at any time. Specifying -refresh causes the cache to be refreshed before being returned.

pdh_enumerate_object_counters PERFOBJ ?options?

Returns a list of the names of counters present in the performance object PERFOBJ. See pdh_enumerate_object_items for valid options.

pdh_enumerate_object_instances PERFOBJ ?options?

Returns a list of the names of instances of the performance object PERFOBJ. The list may be empty if the object supports instances but none are present. The command raises an error if PERFOBJ does not support instances at all. See pdh_enumerate_object_items for valid options.

pdh_enumerate_object_items PERFOBJ ?options?

Returns a list of one or two elements, the first being a list of counter names for the performance object PERFOBJ. If the performance object does not support instances, the returned list contains only that element. Otherwise, the second element is the list of instance names for object. This may be empty in the case the performance object supports instances but none are present. The following options may be specified:

-detail DETAILLEVEL	Controls which detail levels are to be returned. DETAILLEVEL may be one of novice, advanced, expert and wizard (default) which return performance objects at an increasing level of detail.
-refresh	The list of performance objects is returned from a cache. Performance objects may be added by any application at any time. The command will fail if PERFOBJ is not in the cache. Specifying -refresh causes the cache to be refreshed before attempting to access the information for PERFOBJ.

pdh_get_array HCOUNTER ?options?

Returns a flat list of instance name and value pairs for a counter that covers multiple objects, such as one containing wildcards. Refer to pdh_get_scalar for options.

Note that the command does not refresh the counter value. Caller must do that with pdh_query_refresh before calling this command if so desired.

pdh_get_scalar HCOUNTER ?options?

Returns the value of the specified counter as of the last call to pdh_query_refresh. HCOUNTER is a handle to a counter as returned by a prior call to pdh_add_counter. If the counter was specified using a wildcard, use pdh_get_array instead to retrieve multiple values for all matching instances.

The following options may be specified:

-format FORMAT	Specifies how the counter value should be formatted. FORMAT may be on of long, large or double for a 32-bit integer, a 64-bit integer or a floating point double.
-scale SCALE	By default, each counter has a default scaling factor. If SCALE is none, the counter value is returned without the default scaling. If SCALE is x1000, the returned value is scaled up by a factor of 1000. If SCALE is nocap100, the counter value is not capped at 100 as is the scale for some counters like processor utilization.
-var VARNAME	Specifies VARNAME as the name of a variable in the caller's context where the counter value is stored instead of being returned as the result of the command. If specified, the return value of the command is 1 on success and 0 if the counter does not exist. Without this option, the command will raise an error if the counter does not exist.

Note that the command does not refresh the counter value. Caller must do that with pdh_query_refresh before calling this command if so desired.

pdh_parse_counter_path CTRPATH

Returns a dictionary containing the components of the counter path CTRPATH. The dictionary contains the following keys corresponding to each component of the path: machine, object, instance, instanceindex, parent and counter.

pdh_query_close HPERF

Closes a performance counter query. All counters added to the query are also released. HPERF is a query handle previously returned by pdh_query_open.

pdh_query_get HPERF ?NAME1 NAME2....?

Returns the values for one or more counters added to the query with pdh_add_counter. If no arguments are specified, values for all counters added to the query are returned. Otherwise, each argument must be the name associated with the counter with the -name option to the pdh_add_counter command.

The counters are refreshed with their current values from the system before being returned.

The returned value is a dictionary, each key of which is the mnemonic name associated with the abovementioned -name option of pdh_add_counter. The corresponding value in the dictionary may be a scalar or an array (as returned by the pdh_get_array command) depending on whether the -array option was specified as true in the corresponding pdh_add_counter call.

pdh_query_open

Open a new performance counter query and returns a handle to it. Counters can be added and removed from the query using The query must be closed when no longer needed by calling pdh_query_close.

pdh_query_refresh HPERF

Refreshes all counters in the specified performance counter query with their current values from the system. HPERF is a query handle previously returned by pdh_query_open.

In the case of rate-based counters like processor utilization, the first call only serves to initialize the counters. Valid data is collected only from the second call onwards. Microsoft recommends calls be at least one second apart.

pdh_remove_counter HPERF CTRNAME

Removes a counter from a performance counter query. Counters are automatically released when a query is closed. However, if a counter is no longer of use but the other counters in the query are, this command can be used to remove it.

pdh_system_performance_query ?CTRNAME ....?

This is a wrapper around pdh_query_open that includes some commonly used system counters.

Calling the command without any arguments will return a list of counter mnemonics that the command understands.

If called with arguments, each argument must be the name of a counter mnemonic. The command then returns a handle to a performance query with those counters already added. The command also internally calls pdh_query_refresh.

The returned query handle can be used exactly as a handle from pdh_query_open including addition of more counters, retrieving counter values etc. It must also be closed in the same manner by calling pdh_query_close.

Performance Counters

SYNOPSIS

DESCRIPTION

Performance Objects

Counter Paths

Retrieving Counter Values

Commands

COPYRIGHT

TWAPI 4.6.0 Documentation