pdhutil

package
v0.0.0-...-45a9bcf Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 3, 2024 License: Apache-2.0 Imports: 15 Imported by: 0

README

Handling of counter strings and translations in windows

Windows counter classes and counter names are localized in Windows. This presents an extra degree of difficulty in reporting performance counters on Windows platforms.

Storage

The strings for the counter classes and counter names are stored in the registry. They are stored in the key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib. Beneath that key is a key 009 (for English), and a second key CurrentLanguage which contains the strings for the currently enabled locale. On an en-us locale, the two keys contain the same information.

The strings are stored as a REG_MULTI_SZ, which means it is a "C" language string; in fact, it is a list of NULL terminated strings, with the last element indicated by NULLNULL. For example, the contents might be (shortened for clarity): "1|N|1847|N|2|N|System|N|4|N|Memory|N||N|" (where |N| is NULL)

To find the string for the current locale, in this example "System", first traverse the list of english strings. System has the index "2". Then, find the string with the index "2" in the current language, and Voila.

Duplication

Because each package that reports counters via the performance counter API registers its own strings, strings can be duplicated. For example, the string "Write Bytes/sec" appears 4 times in one sample machine.

In addition, each of those might be translated differently. The translation to the locale "foo" might have one instance "Write Bytes/sec" translated to "FooWrite Bytes/sec", and a second translated to "FooWrite Bytes per second".

This is because the first might be from the "System" package, and the second might be from the "NTDS" package, and the translations were generated separately.

The result of this is that while you use the same English string for two counters

  • \NTDS(*)\Write Bytes/sec
  • \System(*)\Write Bytes/sec

On a "fooish" locale, the counters would be

  • \NTDS(*)\FooWrite Bytes/sec
  • \System(*)\FooWrite Bytes per second

And, there is no way to know in advance which string to use.

Therefore, the (somewhat messy) algorithm in MakeCounterPath() is to look up the string in the string table, and find the counter name that works. Using the "fooish" example above, that means

  1. Look up the index for "Write Bytes/sec". This returns two indices A and B
  2. Retrieve the fooish string for index A, "FooWrite Bytes/sec"
  3. Attempt to create the counter "\System(*)\FooWrite Bytes/sec"
  • this will fail, because that counter doesn't exist (because it's not the correctly translated string)
  1. Attempt to create the counter "\System(*)\FooWrite Bytes per second"
  • This will succeed, because we've found the correct translation of the given English string.

Documentation

Rendered for windows/amd64

Overview

Package pdhutil provides the Windows PDH API

Index

Constants

View Source
const (

	//
	// Event Descriptors
	//
	PDH_CSTATUS_VALID_DATA                     = 0x0
	PDH_CSTATUS_NEW_DATA                       = 0x1
	PDH_CSTATUS_NO_MACHINE                     = 0x800007D0
	PDH_CSTATUS_NO_INSTANCE                    = 0x800007D1
	PDH_MORE_DATA                              = 0x800007D2
	PDH_CSTATUS_ITEM_NOT_VALIDATED             = 0x800007D3
	PDH_RETRY                                  = 0x800007D4
	PDH_NO_DATA                                = 0x800007D5
	PDH_CALC_NEGATIVE_DENOMINATOR              = 0x800007D6
	PDH_CALC_NEGATIVE_TIMEBASE                 = 0x800007D7
	PDH_CALC_NEGATIVE_VALUE                    = 0x800007D8
	PDH_DIALOG_CANCELLED                       = 0x800007D9
	PDH_END_OF_LOG_FILE                        = 0x800007DA
	PDH_ASYNC_QUERY_TIMEOUT                    = 0x800007DB
	PDH_CANNOT_SET_DEFAULT_REALTIME_DATASOURCE = 0x800007DC
	PDH_UNABLE_MAP_NAME_FILES                  = 0x80000BD5
	PDH_PLA_VALIDATION_WARNING                 = 0x80000BF3
	PDH_CSTATUS_NO_OBJECT                      = 0xC0000BB8
	PDH_CSTATUS_NO_COUNTER                     = 0xC0000BB9
	PDH_CSTATUS_INVALID_DATA                   = 0xC0000BBA
	PDH_MEMORY_ALLOCATION_FAILURE              = 0xC0000BBB
	PDH_INVALID_HANDLE                         = 0xC0000BBC
	PDH_INVALID_ARGUMENT                       = 0xC0000BBD
	PDH_FUNCTION_NOT_FOUND                     = 0xC0000BBE
	PDH_CSTATUS_NO_COUNTERNAME                 = 0xC0000BBF
	PDH_CSTATUS_BAD_COUNTERNAME                = 0xC0000BC0
	PDH_INVALID_BUFFER                         = 0xC0000BC1
	PDH_INSUFFICIENT_BUFFER                    = 0xC0000BC2
	PDH_CANNOT_CONNECT_MACHINE                 = 0xC0000BC3
	PDH_INVALID_PATH                           = 0xC0000BC4
	PDH_INVALID_INSTANCE                       = 0xC0000BC5
	PDH_INVALID_DATA                           = 0xC0000BC6
	PDH_NO_DIALOG_DATA                         = 0xC0000BC7
	PDH_CANNOT_READ_NAME_STRINGS               = 0xC0000BC8
	PDH_LOG_FILE_CREATE_ERROR                  = 0xC0000BC9
	PDH_LOG_FILE_OPEN_ERROR                    = 0xC0000BCA
	PDH_LOG_TYPE_NOT_FOUND                     = 0xC0000BCB
	PDH_NO_MORE_DATA                           = 0xC0000BCC
	PDH_ENTRY_NOT_IN_LOG_FILE                  = 0xC0000BCD
	PDH_DATA_SOURCE_IS_LOG_FILE                = 0xC0000BCE
	PDH_DATA_SOURCE_IS_REAL_TIME               = 0xC0000BCF
	PDH_UNABLE_READ_LOG_HEADER                 = 0xC0000BD0
	PDH_FILE_NOT_FOUND                         = 0xC0000BD1
	PDH_FILE_ALREADY_EXISTS                    = 0xC0000BD2
	PDH_NOT_IMPLEMENTED                        = 0xC0000BD3
	PDH_STRING_NOT_FOUND                       = 0xC0000BD4
	PDH_UNKNOWN_LOG_FORMAT                     = 0xC0000BD6
	PDH_UNKNOWN_LOGSVC_COMMAND                 = 0xC0000BD7
	PDH_LOGSVC_QUERY_NOT_FOUND                 = 0xC0000BD8
	PDH_LOGSVC_NOT_OPENED                      = 0xC0000BD9
	PDH_WBEM_ERROR                             = 0xC0000BDA
	PDH_ACCESS_DENIED                          = 0xC0000BDB
	PDH_LOG_FILE_TOO_SMALL                     = 0xC0000BDC
	PDH_INVALID_DATASOURCE                     = 0xC0000BDD
	PDH_INVALID_SQLDB                          = 0xC0000BDE
	PDH_NO_COUNTERS                            = 0xC0000BDF
	PDH_SQL_ALLOC_FAILED                       = 0xC0000BE0
	PDH_SQL_ALLOCCON_FAILED                    = 0xC0000BE1
	PDH_SQL_EXEC_DIRECT_FAILED                 = 0xC0000BE2
	PDH_SQL_FETCH_FAILED                       = 0xC0000BE3
	PDH_SQL_ROWCOUNT_FAILED                    = 0xC0000BE4
	PDH_SQL_MORE_RESULTS_FAILED                = 0xC0000BE5
	PDH_SQL_CONNECT_FAILED                     = 0xC0000BE6
	PDH_SQL_BIND_FAILED                        = 0xC0000BE7
	PDH_CANNOT_CONNECT_WMI_SERVER              = 0xC0000BE8
	PDH_PLA_COLLECTION_ALREADY_RUNNING         = 0xC0000BE9
	PDH_PLA_ERROR_SCHEDULE_OVERLAP             = 0xC0000BEA
	PDH_PLA_COLLECTION_NOT_FOUND               = 0xC0000BEB
	PDH_PLA_ERROR_SCHEDULE_ELAPSED             = 0xC0000BEC
	PDH_PLA_ERROR_NOSTART                      = 0xC0000BED
	PDH_PLA_ERROR_ALREADY_EXISTS               = 0xC0000BEE
	PDH_PLA_ERROR_TYPE_MISMATCH                = 0xC0000BEF
	PDH_PLA_ERROR_FILEPATH                     = 0xC0000BF0
	PDH_PLA_SERVICE_ERROR                      = 0xC0000BF1
	PDH_PLA_VALIDATION_ERROR                   = 0xC0000BF2
	PDH_PLA_ERROR_NAME_TOO_LONG                = 0xC0000BF4
	PDH_INVALID_SQL_LOG_FORMAT                 = 0xC0000BF5
	PDH_COUNTER_ALREADY_IN_QUERY               = 0xC0000BF6
	PDH_BINARY_LOG_CORRUPT                     = 0xC0000BF7
	PDH_LOG_SAMPLE_TOO_SMALL                   = 0xC0000BF8
	PDH_OS_LATER_VERSION                       = 0xC0000BF9
	PDH_OS_EARLIER_VERSION                     = 0xC0000BFA
	PDH_INCORRECT_APPEND_TIME                  = 0xC0000BFB
	PDH_UNMATCHED_APPEND_COUNTER               = 0xC0000BFC
	PDH_SQL_ALTER_DETAIL_FAILED                = 0xC0000BFD
	PDH_QUERY_PERF_DATA_TIMEOUT                = 0xC0000BFE
	MSG_Publisher_Name                         = 0x90000001
)

PDH error codes. Taken from latest PDHMSH.h in Windows SDK

https://learn.microsoft.com/en-us/windows/win32/perfctrs/pdh-error-codes

View Source
const (
	PDH_FMT_RAW          = uint32(0x00000010)
	PDH_FMT_ANSI         = uint32(0x00000020)
	PDH_FMT_UNICODE      = uint32(0x00000040)
	PDH_FMT_LONG         = uint32(0x00000100)
	PDH_FMT_DOUBLE       = uint32(0x00000200)
	PDH_FMT_LARGE        = uint32(0x00000400)
	PDH_FMT_NOSCALE      = uint32(0x00001000)
	PDH_FMT_1000         = uint32(0x00002000)
	PDH_FMT_NODATA       = uint32(0x00004000)
	PDH_FMT_NOCAP100     = uint32(0x00008000)
	PERF_DETAIL_COSTLY   = uint32(0x00010000)
	PERF_DETAIL_STANDARD = uint32(0x0000FFFF)
)

dwFormat flag values taken from latest pdh.h in windows sdk

View Source
const (
	CounterAllProcessPctProcessorTime   = `\Process(*)\% Processor Time`
	CounterAllProcessPctUserTime        = `\Process(*)\% User Time`
	CounterAllProcessPctPrivilegedTime  = `\Process(*)\% Privileged Time`
	CounterAllProcessVirtualBytesPeak   = `\Process(*)\Virtual Bytes Peak`
	CounterAllProcessVirtualBytes       = `\Process(*)\Virtual Bytes`
	CounterAllProcessPageFaultsPerSec   = `\Process(*)\Page Faults/sec`
	CounterAllProcessWorkingSetPeak     = `\Process(*)\Working Set Peak`
	CounterAllProcessWorkingSet         = `\Process(*)\Working Set`
	CounterAllProcessPageFileBytesPeak  = `\Process(*)\Page File Bytes Peak`
	CounterAllProcessPageFileBytes      = `\Process(*)\Page File Bytes`
	CounterAllProcessPrivateBytes       = `\Process(*)\Private Bytes`
	CounterAllProcessThreadCount        = `\Process(*)\Thread Count`
	CounterAllProcessPriorityBase       = `\Process(*)\Priority Base`
	CounterAllProcessElapsedTime        = `\Process(*)\Elapsed Time`
	CounterAllProcessPID                = `\Process(*)\ID Process`
	CounterAllProcessParentPID          = `\Process(*)\Creating Process ID`
	CounterAllProcessPoolPagedBytes     = `\Process(*)\Pool Paged Bytes`
	CounterAllProcessPoolNonpagedBytes  = `\Process(*)\Pool Nonpaged Bytes`
	CounterAllProcessHandleCount        = `\Process(*)\Handle Count`
	CounterAllProcessIOReadOpsPerSec    = `\Process(*)\IO Read Operations/sec`
	CounterAllProcessIOWriteOpsPerSec   = `\Process(*)\IO Write Operations/sec`
	CounterAllProcessIODataOpsPerSec    = `\Process(*)\IO Data Operations/sec`
	CounterAllProcessIOOtherOpsPerSec   = `\Process(*)\IO Other Operations/sec`
	CounterAllProcessIOReadBytesPerSec  = `\Process(*)\IO Read Bytes/sec`
	CounterAllProcessIOWriteBytesPerSec = `\Process(*)\IO Write Bytes/sec`
	CounterAllProcessIODataBytesPerSec  = `\Process(*)\IO Data Bytes/sec`
	CounterAllProcessIOOtherBytesPerSec = `\Process(*)\IO Other Bytes/sec`
	CounterAllProcessWorkingSetPrivate  = `\Process(*)\Working Set - Private`
)

English counters for the Process counterset

View Source
const (
	// taken from winperf.h
	PERF_DETAIL_NOVICE   = 100 // The uninformed can understand it
	PERF_DETAIL_ADVANCED = 200 // For the advanced user
	PERF_DETAIL_EXPERT   = 300 // For the expert user
	PERF_DETAIL_WIZARD   = 400 // For the system designer
)

https://learn.microsoft.com/en-us/windows/win32/api/winperf/ns-winperf-perf_object_type

Variables

This section is empty.

Functions

func AddCounterInstance

func AddCounterInstance(clss, inst string)

AddCounterInstance adds a specific instance to the table of available instances

func AddToQuery

func AddToQuery(query *PdhQuery, counter PdhCounter) error

AddToQuery calls PdhCounter.AddToQuery and handles initError logic Counters should implement PdhCounter.AddToQuery to override init logic

func PdhAddEnglishCounter

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

PdhAddEnglishCounter adds the specified counter to the query

Parameters hQuery [in] Handle to the query to which you want to add the counter. This handle is returned by the PdhOpenQuery function. szFullCounterPath [in] Null-terminated string that contains the counter path. For details on the format of a counter path, see Specifying a Counter Path. The maximum length of a counter path is PDH_MAX_COUNTER_PATH. dwUserData [in] User-defined value. This value becomes part of the counter information. To retrieve this value later, call the PdhGetCounterInfo function and access the dwUserData member of the PDH_COUNTER_INFO structure. phCounter [out] Handle to the counter that was added to the query. You may need to reference this handle in subsequent calls.

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 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.

Parameters szDataSource [in] Null-terminated string that specifies the name of the log file from which to retrieve performance data. If NULL, performance data is collected from a real-time data source.

dwUserData [in] User-defined value to associate with this query. To retrieve the user data later, call PdhGetCounterInfo and access the dwQueryUserData member of PDH_COUNTER_INFO.

phQuery [out] Handle to the query. You use this handle in subsequent calls.

func PdhRemoveCounter

func PdhRemoveCounter(hCounter PDH_HCOUNTER) uint32

PdhRemoveCounter removes a counter from a query

func RemoveCounterInstance

func RemoveCounterInstance(clss, inst string)

RemoveCounterInstance removes a specific instance from the table of available instances

func SetQueryReturnValue

func SetQueryReturnValue(counter string, val float64)

SetQueryReturnValue provides an entry point for tests to set expected values for a given counter

func SetupTesting

func SetupTesting(_, countersfile string)

SetupTesting initializes the PDH libarary with the mock functions rather than the real thing

Types

type AvailableCounters

type AvailableCounters struct {
	// contains filtered or unexported fields
}

AvailableCounters houses the mocked version of the available counters & instances

func ReadCounters

func ReadCounters(fn string) (AvailableCounters, error)

ReadCounters reads the available PDH counters from a static text file

type CounterInstanceVerify

type CounterInstanceVerify func(string) bool

CounterInstanceVerify is a callback function called by GetAllValues for each instance of the counter. Implementation should return true if that instance should be included, false otherwise

type CounterStrings

type CounterStrings struct {
	// contains filtered or unexported fields
}

CounterStrings houses the mocked version of the registry-based counter strings database

func ReadCounterStrings

func ReadCounterStrings(fn string) (CounterStrings, error)

ReadCounterStrings reads the counter strings from the provided file

type ErrPdhInvalidInstance

type ErrPdhInvalidInstance struct {
	// contains filtered or unexported fields
}

ErrPdhInvalidInstance is returned when a counter instance is invalid

func NewErrPdhInvalidInstance

func NewErrPdhInvalidInstance(message string) *ErrPdhInvalidInstance

NewErrPdhInvalidInstance creates a new ErrPdhInvalidInstance

func (*ErrPdhInvalidInstance) Error

func (e *ErrPdhInvalidInstance) Error() string

type PDH_COUNTER_PATH_ELEMENTS

type PDH_COUNTER_PATH_ELEMENTS struct {
	// contains filtered or unexported fields
}

PDH_COUNTER_PATH_ELEMENTS struct

https://learn.microsoft.com/en-us/windows/win32/api/pdh/ns-pdh-pdh_counter_path_elements_w

type PDH_FMT_COUNTERVALUE_DOUBLE

type PDH_FMT_COUNTERVALUE_DOUBLE struct {
	CStatus     uint32
	DoubleValue float64
}

PDH_FMT_COUNTERVALUE_DOUBLE is a union specialization for double values

https://learn.microsoft.com/en-us/windows/win32/api/pdh/ns-pdh-pdh_fmt_countervalue

type PDH_FMT_COUNTERVALUE_ITEM_DOUBLE

type PDH_FMT_COUNTERVALUE_ITEM_DOUBLE struct {
	// contains filtered or unexported fields
}

PDH_FMT_COUNTERVALUE_ITEM_DOUBLE structure contains the instance name and formatted value of a PDH_FMT_COUNTERVALUE_DOUBLE counter.

type PDH_FMT_COUNTERVALUE_ITEM_LARGE

type PDH_FMT_COUNTERVALUE_ITEM_LARGE struct {
	// contains filtered or unexported fields
}

PDH_FMT_COUNTERVALUE_ITEM_LARGE structure contains the instance name and formatted value of a PDH_FMT_COUNTERVALUE_LARGE counter.

type PDH_FMT_COUNTERVALUE_ITEM_LONG

type PDH_FMT_COUNTERVALUE_ITEM_LONG struct {
	// contains filtered or unexported fields
}

PDH_FMT_COUNTERVALUE_ITEM_LONG structure contains the instance name and formatted value of a PDH_FMT_COUNTERVALUE_LONG counter.

type PDH_FMT_COUNTERVALUE_LARGE

type PDH_FMT_COUNTERVALUE_LARGE struct {
	CStatus    uint32
	LargeValue int64
}

PDH_FMT_COUNTERVALUE_LARGE is a union specialization for 64 bit integer values

https://learn.microsoft.com/en-us/windows/win32/api/pdh/ns-pdh-pdh_fmt_countervalue

type PDH_FMT_COUNTERVALUE_LONG

type PDH_FMT_COUNTERVALUE_LONG struct {
	CStatus uint32

	LongValue int32
	// contains filtered or unexported fields
}

PDH_FMT_COUNTERVALUE_LONG is a union specialization for long values

https://learn.microsoft.com/en-us/windows/win32/api/pdh/ns-pdh-pdh_fmt_countervalue

type PDH_HCOUNTER

type PDH_HCOUNTER windows.Handle

PDH_HCOUNTER is a handle to a PDH counter

type PDH_HQUERY

type PDH_HQUERY windows.Handle

PDH_HQUERY is a handle to a PDH query

type PdhCounter

type PdhCounter interface {
	// Return true if a query should attempt to initialize this counter.
	// Return false if a query must not attempt to initialize this counter.
	ShouldInit() bool

	// Called during (*PdhQuery).CollectQueryData via AddToQuery() for counters that return true from ShouldInit()
	// Must call the appropriate PdhAddCounter/PdhAddEnglishCounter function to add the
	// counter to the query.
	AddToQuery(*PdhQuery) error

	// Given the result of PdhCounter.AddToQuery, should update initError and initFailCount
	SetInitError(error) error

	// Calls PdhRemoveCounter and updates internal state (handle field)
	Remove() error
}

PdhCounter manages behavior common to all types of PDH counters https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhaddenglishcounterw

type PdhCounterValue

type PdhCounterValue struct {
	CStatus uint32
	Double  float64
	Large   int64
	Long    int32
}

PdhCounterValue represents a counter value

type PdhCounterValueItem

type PdhCounterValueItem struct {
	// contains filtered or unexported fields
}

PdhCounterValueItem contains the counter value for an instance

type PdhEnglishMultiInstanceCounter

type PdhEnglishMultiInstanceCounter struct {
	// contains filtered or unexported fields
}

PdhEnglishMultiInstanceCounter is a specialization for multi-instance counters https://learn.microsoft.com/en-us/windows/win32/perfctrs/about-performance-counters

func (*PdhEnglishMultiInstanceCounter) AddToQuery

func (counter *PdhEnglishMultiInstanceCounter) AddToQuery(query *PdhQuery) error

Implements PdhCounter.AddToQuery for english counters.

func (*PdhEnglishMultiInstanceCounter) GetAllValues

func (counter *PdhEnglishMultiInstanceCounter) GetAllValues() (values map[string]float64, err error)

GetAllValues returns the data associated with each instance in a counter. verifyfn is used to filter out instance names that are returned instance:value pairs are not returned for items whose CStatus contains an error

type PdhEnglishSingleInstanceCounter

type PdhEnglishSingleInstanceCounter struct {
	// contains filtered or unexported fields
}

PdhEnglishSingleInstanceCounter is a specialization for single-instance counters https://learn.microsoft.com/en-us/windows/win32/perfctrs/about-performance-counters

func (*PdhEnglishSingleInstanceCounter) AddToQuery

func (counter *PdhEnglishSingleInstanceCounter) AddToQuery(query *PdhQuery) error

Implements PdhCounter.AddToQuery for english counters.

func (*PdhEnglishSingleInstanceCounter) GetValue

func (counter *PdhEnglishSingleInstanceCounter) GetValue() (float64, error)

GetValue returns the data associated with a single-value counter

type PdhFormatter

type PdhFormatter struct {
}

PdhFormatter implements a formatter for PDH performance counters

func (*PdhFormatter) Enum

func (f *PdhFormatter) Enum(counterName string, hCounter PDH_HCOUNTER, format uint32, ignoreInstances []string, fn ValueEnumFunc) error

Enum enumerates performance counter values for a wildcard instance counter (e.g. `\Process(*)\% Processor Time`)

type PdhMultiInstanceCounter

type PdhMultiInstanceCounter interface {
	PdhCounter
	// Return a map of instance name -> counter value formatted as a float
	GetAllValues() (map[string]float64, error)
}

PdhMultiInstanceCounter manages a PDH counter that can have multiple instances Returns a value for every instance https://learn.microsoft.com/en-us/windows/win32/perfctrs/specifying-a-counter-path

type PdhQuery

type PdhQuery struct {
	Handle PDH_HQUERY
	// contains filtered or unexported fields
}

PdhQuery manages a PDH Query https://learn.microsoft.com/en-us/windows/win32/perfctrs/creating-a-query https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhopenqueryw

func CreatePdhQuery

func CreatePdhQuery() (*PdhQuery, error)

CreatePdhQuery creates a query that can have counters added to it

https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhopenqueryw

func (*PdhQuery) AddCounter

func (query *PdhQuery) AddCounter(counter PdhCounter)

AddCounter adds a counter to the list of counters managed by a PdhQuery. It does NOT add the Windows counter to the Windows query.

func (*PdhQuery) AddEnglishCounterInstance

func (query *PdhQuery) AddEnglishCounterInstance(objectName string, counterName string, instanceName string) PdhSingleInstanceCounter

AddEnglishCounterInstance returns a PdhSingleInstanceCounter that will fetch the value of a given instance of the given counter. the objectName and counterName must be in English. See PdhAddEnglishCounter docs for details https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhaddenglishcounterw

Implementation detail: This function does not actually call the Windows API PdhAddEnglishCounter. That happens

when (*PdhQuery).CollectQueryData calls AddToQuery. This function only links our pdhCounter struct
to our PdhQuery struct.
We do this so we can handle several PDH error cases and their recovery behind the scenes to reduce
duplicate/error prone code in the checks that uses this package.
For example, see tryRefreshPdhObjectCache().
This function cannot fail, if it does then the checks that use it will need to be
restructured so that their Configure() call does not fail if the counter is not available
right away on host boot (see https://github.com/DataDog/datadog-agent/pull/13101).
All errors related to the counter are returned from the GetValue()/GetAllValues() function.

func (*PdhQuery) AddEnglishMultiInstanceCounter

func (query *PdhQuery) AddEnglishMultiInstanceCounter(objectName string, counterName string, verifyfn CounterInstanceVerify) PdhMultiInstanceCounter

AddEnglishMultiInstanceCounter returns a PdhMultiInstanceCounter that will fetch values for all instances of a counter. This uses a '*' wildcard to collect values for all instances of a counter. Instances/values can be filtered manually once returned from GetAllValues() or with verifyfn (see CounterInstanceVerify)

Implementation detail: See AddEnglishCounterInstance()

func (*PdhQuery) AddEnglishSingleInstanceCounter

func (query *PdhQuery) AddEnglishSingleInstanceCounter(objectName string, counterName string) PdhSingleInstanceCounter

AddEnglishSingleInstanceCounter returns a PdhSingleInstanceCounter that will fetch a single instance counter value. the objectName and counterName must be in English. See PdhAddEnglishCounter docs for details https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhaddenglishcounterw

Implementation detail: See AddEnglishCounterInstance()

func (*PdhQuery) Close

func (query *PdhQuery) Close()

Close closes the query handle, freeing the underlying windows resources. It is not necessary to remove the counters from the query before calling this function. PdhCloseQuery closes all counter handles associated with the query. https://learn.microsoft.com/en-us/windows/win32/perfctrs/creating-a-query

func (*PdhQuery) CollectQueryData

func (query *PdhQuery) CollectQueryData() error

CollectQueryData updates the counter values managed by the query.

Adds any Windows counters not yet added to the Windows query.

Must be called before GetValue/GetAllValues to make new counter values available. https://learn.microsoft.com/en-us/windows/win32/api/pdh/nf-pdh-pdhcollectquerydata

type PdhSingleInstanceCounter

type PdhSingleInstanceCounter interface {
	PdhCounter
	// Return the counter value formatted as a float
	GetValue() (float64, error)
}

PdhSingleInstanceCounter manages a PDH counter with no instance or for a specific instance Only a single value is returned. https://learn.microsoft.com/en-us/windows/win32/perfctrs/specifying-a-counter-path

type ValueEnumFunc

type ValueEnumFunc func(s string, v PdhCounterValue)

ValueEnumFunc implements a callback for counter enumeration

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL