WINDOWS PERFMON Plug-in - Technical Reference

Introduction

Geneos PERFMON Plug-in brings Windows Performance seamlessly and in real-time into the Geneos 'world'. These parameters become fully Geneos manageable.

In addition to translating Windows Performance parameters into native variables, Geneos PERFMON Knowledge Module enables effective monitoring by providing a 'value added' layer. This layer is based on defining a number of user configurable templates that define mapping of the Windows Performance parameters.

This additional layer provides the following benefits:

  • Hide Windows Performance variables organisational complexity - ability to concentrate on the key parameters to manage.
  • Remove Windows version dependency. The names and hierarchical positions of the Windows Performance parameters vary between different versions of Windows.

Views

PERFMON Plug-in allows great flexibility in the way views can be defined. Each instance of the PERFMON Plug-in will create a single view with a title as per the name provided in the SamplerList. Multiple PERFMON samplers can be processed by the same netprobe in order to obtain a full range of parameters.

View

windows-perfmon2

windows-perfmon3

Plug-in Configuration

The following parameters can be configured for this plug-in. For object ID and counter ID parameters, it has been observed that numeric ID values for these parameter may not always be resolved by the native Windows Performance Data Helper APIs used by the PERFMON Plug-in. In such cases, it is advisable to use the corresponding text strings for the object and counter IDs over the numeric ID values.

template

The template specifies the contents that are used to populate a view.

The template > headlineVariables section is used to specify view headline variables. This section is optional.

The table is specified either by the template > tableDefinition section or the template > records section. (Only one of the 2 sections may be specified.)

In order to construct a template, the full list of the PerfMon variables can be displayed. See WINDOWS PERFMON Plug-in - Technical Reference.

Mandatory: Yes

template > headlineVariables

The variables are defined in terms of objected, instance and counterID.

For example:

headlineVariables
        headlineVariable
                name: connectionsEstablished
                objectID: 638
                instance: -
                counterID: 642
        headlineVariable
                name: connectionsFailures
                objectID: 638
                instance: -
                counterID: 648

Mandatory: No

template > headlineVariables > headlineVariable > name

The name of the headline variable to create

Mandatory: Yes if a headline has been defined

template > headlineVariables > headlineVariable > objectID

The performance object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a headline has been defined

template > headlineVariables > headlineVariable > instance

The instance of the object to query. If this is not applicable then this should be '-'

Mandatory: Yes if a headline has been defined

template > headlineVariables > headlineVariable > counterID

The counter of the object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a headline has been defined

template > headlines

Deprecated: see template > headlineVariables.

The variables are defined in terms of objected, instance and counterID.

For example:

headlines
        headline
                name: connectionsEstablished
                objectID: 638
                instance: -
                counterID: 642
        headline
                name: connectionsFailures
                objectID: 638
                instance: -
                counterID: 648

Mandatory: No

template > headlines > headline > name

Deprecated: see template > headlineVariables.

The name of the headline variable to create

Mandatory: Yes if a headline has been defined

template > headlines > headline > objectID

Deprecated: see template > headlineVariables.

The performance object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a headline has been defined

template > headlines > headline > instance

Deprecated: see template > headlineVariables.

The instance of the object to query. If this is not applicable then this should be '-'

Mandatory: Yes if a headline has been defined

template > headlines > headline > counterID

Deprecated: see template > headlineVariables.

The counter of the object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a headline has been defined

template > tableDefinition

This section constructs a table in the view. This is useful for a set of variables that has instances, so that each instance can be represented as a table row and the counters are represented as table columns.

When instances are specified, only the instances that match the tokens in the list are shown. By default all instances are shown.

For example:

tableDefinition
        objectID: 230
        instances
                instance: lemmy
                instance: CMD
        counters
                counter
                        name: handleCount
                        value: Handle Count
                counter
                        name: privTime
                        value: 952

Mandatory: Yes if a table has been defined

template > tableDefinition > objectID

The performance object to query for the contents of this table. This can be entered as a text string or a numeric ID

Mandatory: Yes if a table has been defined and objectRegularExpression has not.

template > tableDefinition > objectRegularExpression

A regular expression used to find performance objects to query for the contents of this table. The plug-in will attempt to retrieve values for every object the expression matches against along with the instance and counter definitions that follow.

If the regular expression contains the named capture group "OBJ" then the captured text will be used as a prefix to any instances. Not that OBJ must be in uppercase.

Examples:

Expression Result
process Matches all objects that contain the word process.
^MyApp_(?<OBJ>[\w_-]+) Matches all objects starting with MyApp_ followed by some identifying text.

The regular expression modifier i can be used to make the pattern case insensitive. The modifier s applies to multiline regular expressions and does not apply in this case.

Using the example above the objects MyApp_One, MyApp_Two and MyApp_Three with instances alpha, beta and gamma will result in rows

Instance counters
One - alpha ...
One - beta ...
One - gamma ...
Two - alpha ...
Two - beta ...
Two - gamma ...
Three - alpha ...
Three - beta ...
Three - gamma ...

Where no OBJ named regular expression is found the instance names alone are used. This could lead to non-unique row names.

Instance counters
alpha ...
beta ...
gamma ...
alpha ...
beta ...
gamma ...
alpha ...
beta ...
gamma ...

Where there are objects with no instances the extracted name OBJ name of the object is used.

Instance Counters
One ...
Two ...
Three ...

Alternatively if the OBJ is not defined the full object name is used.

Instance counters
MyApp_One - alpha ...
MyApp_One - beta ...
MyApp_One - gamma ...
MyApp_Two - alpha ...
MyApp_Two - beta ...
MyApp_Two - gamma ...
MyApp_Three - alpha ...
MyApp_Three - beta ...
MyApp_Three - gamma ...

Mandatory: Yes if a table has been defined and objectID has not.

template > tableDefinition > instances

The instances to show in the table. Each instance of the object represents a row in the GENEOS table.

Mandatory: Yes
Default: If not specified then all the instances are shown

template > tableDefinition > counters

The counters to show in the table. Each counter is composed of a name, to be used as the GENEOS column name, and a counterID that specifies the Perfmon counter. The counterID can be entered as a text string or a numeric ID

Mandatory: Yes if a table has been defined

template > table

Deprecated: see template > tableDefinition.

This section constructs a table in the view. This is useful for as set of variables that have instances, so that each instance can be represented as a table row and the counters are represented as table columns.

When instances are specified, only the instances that match the tokens in the list are shown. By default all instances are shown.

For example:

table
        objectID: 230
        instances
                instance: lemmy
                instance: CMD
        counters
                counter
                        name: handleCount
                        value: Handle Count
                counter
                        name: privTime
                        value: 952

Mandatory: Yes if a table has been defined

template > table > objectID

Deprecated: see template > tableDefinition.

The performance object to query for the contents of this table. This can be entered as a text string or a numeric ID

Mandatory: Yes if a table has been defined

template > table > instances

Deprecated: see template > tableDefinition.

The instances to show in the table. Each instance of the object represents a row in the GENEOS table.

Mandatory: Yes
Default: If not specified then all the instances are shown

template > table > counters

Deprecated: see template > tableDefinition.

The counters to show in the table. Each counter is composed of a name, to be used as the GENEOS column name, and a counterID that specifies the Perfmon counter. The counterID can be entered as a text string or a numeric ID

Mandatory: Yes if a table has been defined

template > items

This section constructs a list of record in the view. This should be used when the names of the items to monitor are known at the time the template is created. This section is similar to the template > headlineVariables. Each record will be represented as a single row in the view. A view with 2 columns will be produced. The column called parameterName will be populated with the names specified in the template > items > item > name. The monitored data will be displayed in a column called value.

For example:

items
        item
                name: bytesReceived/sec
                objectID: 510
                instance: VIA Rhine II Fast Ethernet Adapter
                counterID: 264
        item
                name: outputQueueLength
                objectID: 510
                instance: VIA Rhine II Fast Ethernet Adapter
                counterID: 544

Mandatory: No

template > items > item > name

The name of the row to be created for the record

Mandatory: Yes if a record has been defined

template > items > item > objectID

The performance object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a record has been defined

template > items > item > instance

The instance of the object to query. If this is not applicable then this should be '-'

Mandatory: Yes if a record has been defined

template > items > item > counterID

The counter of the object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a record has been defined

template > records

Deprecated: see template > items.

This section constructs a list of record in the view. This should be used when the names of the items to monitor are known at the time the template is created. This section is similar to the headlines section. Each record will be represented as a single row in the view. A view with 2 columns will be produced. The column called parameterName will be populated with the names specified in the template > records > record > name. The monitored data will be displayed in a column called value.

For example:

records
        record
                name: bytesReceived/sec
                objectID: 510
                instance: VIA Rhine II Fast Ethernet Adapter
                counterID: 264
        record
                name: outputQueueLength
                objectID: 510
                instance: VIA Rhine II Fast Ethernet Adapter
                counterID: 544

Mandatory: No

template > records > record > name

Deprecated: see template > items.

The name of the row to be created for the record

Mandatory: Yes if a record has been defined

template > records > record > objectID

Deprecated: see template > items.

The performance object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a record has been defined

template > records > record > instance

Deprecated: see template > items.

The instance of the object to query. If this is not applicable then this should be '-'

Mandatory: Yes if a record has been defined

template > records > record > counterID

Deprecated: see template > items.

The counter of the object to query. This can be entered as a text string or a numeric ID

Mandatory: Yes if a record has been defined

languageID

Deprecated on Windows Vista / Windows 2008 and upwards.

The name of the section in the registery section HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib to read for initialisation data.

Mandatory: No
Default: 009

objectRefreshThreshold

This setting determines the number of samples after which the system will be queried to discover if there are new objects and or instances of objects.

Doing this periodically is less CPU-intensive than continually querying each sample.

When set to 0, the plug-in does not query for new objects or instances of objects throughout its running time, and instead uses objects it initially discovers when it starts.

Mandatory: No
Default: 0

private

The private configuration section holds settings used for debugging the plug-in. Please contact ITRS support if you require assistance with this plug-in.

View the complete set of Windows Performance Parameters

A facility to display the complete set of the available Windows Performance Parameters is used to help designing the View Templates. On Windows, the metric is available either through Perfmon counters or the Windows Management Instruments (WMI) classes. To see which Perfmon counters are accessible to the Netprobe:

  1. In the command prompt, open the Netprobe install folder.
  2. Run the Netprobe with -perf switch and redirect the output to a file:
  3. NetprobeNT.exe -perf > perfmon.txt
  4. Change the filename extension if you are using a different one.

This saves all the Perfmon counters in the perfmon.txt file. Also, this file contains the complete list of all the Windows Performance parameters.

To monitor the virtual memory on a Windows machine, you can use and modify the example XML:

<sampler name="Vantage Virtual Mem Test">
   <plugin>
     <perfmon>
       <template>
         <tableDefinition>
           <objectID>
             <data>230</data>
           </objectID>
           <instances>
           <instance>
             <data>_Total</data>
           </instance>
           </instances>
           <counters>
           <counter>
             <name>
               <data>Process ID</data>
             </name>
             <value>
	        <data>784</data>
	      </value>
	    </counter>
           <counter>
     	      <name>
	        <data>VirtualMemory size(Bytes</data>
	      </name>
	      <value>
		<data>186</data>
	      </value>
	    </counter>
	    </counters>
         </tableDefinition>
       </template>
     </perfmon>
   </plugin>
</sampler>  	

For debugging purposes, it is now possible to change how the perf data is collected before being displayed. The environment variable PERF_TYPE can be set to PDH or REGISTRY.

Note: Windows Vista and Server 2008 cannot use the REGISTRY setting, any attempt to do so defaults to PDH.

The PERF_TYPE defaults to PDH for Windows Vista /Server 2008 and higher, and the Registry for Windows XP and lower if the environment variable is not set.

Note: The Netprobe on Windows Vista and above uses a different mechanism for getting the perf data. On a few counters the ID is shown as 0. If you want to use these counters, you need to use the counter name instead.

Error Description

The following error messages are displayed in a cell and/or headline when errors are encountered in getting their values.

Error Description
Invalid counter The counter of the object is invalid. Check if the counter is configured correctly and if it is a valid counter for the object being queried.
Invalid data The instance of the object does not exist. Check if the instance is a valid instance for the object being queried.
Unable to get formatted value for counter. This error can occur because of either a bug in the provider or an overflow of values in data storage. You can ignore this return value and re-sample to get the new values.