pdh

func PdhAddCounter ¶

func PdhAddCounter(hQuery PDH_HQUERY, szFullCounterPath string, dwUserData uintptr, phCounter *PDH_HCOUNTER) uint32

PdhAddCounter adds the specified counter to the query. This is the internationalized version. Preferably, use the function PdhAddEnglishCounter instead. hQuery is the query handle, which has been fetched by PdhOpenQuery. szFullCounterPath is a full, internationalized counter path (this will differ per Windows language version). dwUserData is a 'user-defined value', which becomes part of the counter information. To retrieve this value later, call PdhGetCounterInfo() and access dwQueryUserData of the PDH_COUNTER_INFO structure.

Examples of szFullCounterPath (in an English version of Windows):

\\Processor(_Total)\\% Idle Time
\\Processor(_Total)\\% Processor Time
\\LogicalDisk(C:)\% Free Space

To view all (internationalized...) counters on a system, there are three non-programmatic ways: perfmon utility, the typeperf command, and the the registry editor. perfmon.exe is perhaps the easiest way, because it's basically a full implemention of the pdh.dll API, except with a GUI and all that. The registry setting also provides an interface to the available counters, and can be found at the following key:

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

This registry key contains several values as follows:

1
1847
2
System
4
Memory
6
% Processor Time
... many, many more

Somehow, these numeric values can be used as szFullCounterPath too:

\2\6 will correspond to \\System\% Processor Time

The typeperf command may also be pretty easy. To find all performance counters, simply execute:

typeperf -qx

func PdhAddEnglishCounter ¶

func PdhAddEnglishCounter(hQuery PDH_HQUERY, szFullCounterPath string, dwUserData uintptr, phCounter *PDH_HCOUNTER) uint32

PdhAddEnglishCounter adds the specified language-neutral counter to the query. See the PdhAddCounter function. This function only exists on Windows versions higher than Vista.

func PdhCloseQuery ¶

func PdhCloseQuery(hQuery PDH_HQUERY) uint32

PdhCloseQuery closes all counters contained in the specified query, closes all handles related to the query, and frees all memory associated with the query.

func PdhCollectQueryData ¶

func PdhCollectQueryData(hQuery PDH_HQUERY) uint32

PdhCollectQueryData collects the current raw data value for all counters in the specified query and updates the status code of each counter. With some counters, this function needs to be repeatedly called before the value of the counter can be extracted with PdhGetFormattedCounterValue(). For example, the following code requires at least two calls:

var handle win.PDH_HQUERY
var counterHandle win.PDH_HCOUNTER
ret := win.PdhOpenQuery(0, 0, &handle)
ret = win.PdhAddEnglishCounter(handle, "\\Processor(_Total)\\% Idle Time", 0, &counterHandle)
var derp win.PDH_FMT_COUNTERVALUE_DOUBLE

ret = win.PdhCollectQueryData(handle)
fmt.Printf("Collect return code is %x\n", ret) // return code will be PDH_CSTATUS_INVALID_DATA
ret = win.PdhGetFormattedCounterValueDouble(counterHandle, 0, &derp)

ret = win.PdhCollectQueryData(handle)
fmt.Printf("Collect return code is %x\n", ret) // return code will be ERROR_SUCCESS
ret = win.PdhGetFormattedCounterValueDouble(counterHandle, 0, &derp)

The PdhCollectQueryData will return an error in the first call because it needs two values for displaying the correct data for the processor idle time. The second call will have a 0 return code.

func PdhGetFormattedCounterArrayDouble ¶

func PdhGetFormattedCounterArrayDouble(hCounter PDH_HCOUNTER, lpdwBufferSize *uint32, lpdwBufferCount *uint32, itemBuffer *PDH_FMT_COUNTERVALUE_ITEM_DOUBLE) uint32

PdhGetFormattedCounterArrayDouble returns an array of formatted counter values. Use this function when you want to format the counter values of a counter that contains a wildcard character for the instance name. The itemBuffer must a slice of type PDH_FMT_COUNTERVALUE_ITEM_DOUBLE. An example of how this function can be used:

okPath := "\\Process(*)\\% Processor Time" // notice the wildcard * character

// ommitted all necessary stuff ...

var bufSize uint32
var bufCount uint32
var size uint32 = uint32(unsafe.Sizeof(win.PDH_FMT_COUNTERVALUE_ITEM_DOUBLE{}))
var emptyBuf [1]win.PDH_FMT_COUNTERVALUE_ITEM_DOUBLE // need at least 1 addressable null ptr.

for {
	// collect
	ret := win.PdhCollectQueryData(queryHandle)
	if ret == win.ERROR_SUCCESS {
		ret = win.PdhGetFormattedCounterArrayDouble(counterHandle, &bufSize, &bufCount, &emptyBuf[0]) // uses null ptr here according to MSDN.
		if ret == win.PDH_MORE_DATA {
			filledBuf := make([]win.PDH_FMT_COUNTERVALUE_ITEM_DOUBLE, bufCount*size)
			ret = win.PdhGetFormattedCounterArrayDouble(counterHandle, &bufSize, &bufCount, &filledBuf[0])
			for i := 0; i < int(bufCount); i++ {
				c := filledBuf[i]
				var s string = win.UTF16PtrToString(c.SzName)
				fmt.Printf("Index %d -> %s, value %v\n", i, s, c.FmtValue.DoubleValue)
			}

			filledBuf = nil
			// Need to at least set bufSize to zero, because if not, the function will not
			// return PDH_MORE_DATA and will not set the bufSize.
			bufCount = 0
			bufSize = 0
		}

		time.Sleep(2000 * time.Millisecond)
	}
}

func PdhGetFormattedCounterArrayLarge ¶

func PdhGetFormattedCounterArrayLarge(hCounter PDH_HCOUNTER, lpdwBufferSize *uint32, lpdwBufferCount *uint32, itemBuffer *PDH_FMT_COUNTERVALUE_ITEM_LARGE) uint32

PdhGetFormattedCounterArrayLarge returns an array of formatted counter values. Use this function when you want to format the counter values of a counter that contains a wildcard character for the instance name. The itemBuffer must a slice of type PDH_FMT_COUNTERVALUE_ITEM_LARGE. For an example usage, see PdhGetFormattedCounterArrayDouble.

func PdhGetFormattedCounterArrayLong ¶

func PdhGetFormattedCounterArrayLong(hCounter PDH_HCOUNTER, lpdwBufferSize *uint32, lpdwBufferCount *uint32, itemBuffer *PDH_FMT_COUNTERVALUE_ITEM_LONG) uint32

PdhGetFormattedCounterArrayLong returns an array of formatted counter values. Use this function when you want to format the counter values of a counter that contains a wildcard character for the instance name. The itemBuffer must a slice of type PDH_FMT_COUNTERVALUE_ITEM_LONG. For an example usage, see PdhGetFormattedCounterArrayDouble.

BUG(krpors): See description of PdhGetFormattedCounterValueLong().

func PdhGetFormattedCounterValueDouble ¶

func PdhGetFormattedCounterValueDouble(hCounter PDH_HCOUNTER, lpdwType *uint32, pValue *PDH_FMT_COUNTERVALUE_DOUBLE) uint32

PdhGetFormattedCounterValueDouble formats the given hCounter using a 'double'. The result is set into the specialized union struct pValue. This function does not directly translate to a Windows counterpart due to union specialization tricks.

func PdhGetFormattedCounterValueLarge ¶

func PdhGetFormattedCounterValueLarge(hCounter PDH_HCOUNTER, lpdwType *uint32, pValue *PDH_FMT_COUNTERVALUE_LARGE) uint32

PdhGetFormattedCounterValueLarge formats the given hCounter using a large int (int64). The result is set into the specialized union struct pValue. This function does not directly translate to a Windows counterpart due to union specialization tricks.

func PdhGetFormattedCounterValueLong ¶

func PdhGetFormattedCounterValueLong(hCounter PDH_HCOUNTER, lpdwType *uint32, pValue *PDH_FMT_COUNTERVALUE_LONG) uint32

PdhGetFormattedCounterValueLong formats the given hCounter using a 'long'. The result is set into the specialized union struct pValue. This function does not directly translate to a Windows counterpart due to union specialization tricks.

BUG(krpors): Testing this function on multiple systems yielded inconsistent results. For instance, the pValue.LongValue kept the value '192' on test system A, but on B this was '0', while the padding bytes of the struct got the correct value. Until someone can figure out this behaviour, prefer to use the Double or Large counterparts instead. These functions provide actually the same data, except in a different, working format.

func PdhOpenQuery ¶

func PdhOpenQuery(szDataSource uintptr, dwUserData uintptr, phQuery *PDH_HQUERY) uint32

PdhOpenQuery creates a new query that is used to manage the collection of performance data. szDataSource is a null terminated string that specifies the name of the log file from which to retrieve the performance data. If 0, performance data is collected from a real-time data source. dwUserData is a user-defined value to associate with this query. To retrieve the user data later, call PdhGetCounterInfo and access dwQueryUserData of the PDH_COUNTER_INFO structure. phQuery is the handle to the query, and must be used in subsequent calls. This function returns a PDH_ constant error code, or ERROR_SUCCESS if the call succeeded.

func PdhValidatePath ¶

func PdhValidatePath(path string) uint32

PdhValidatePath validates a path. Will return ERROR_SUCCESS when ok, or PDH_CSTATUS_BAD_COUNTERNAME when the path is erroneous.