WINDOWS PERFMON Plug-in - Technical Reference

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:

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

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

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

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

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.

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.

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.

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.

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:

NetprobeNT.exe -perf > perfmon.txt

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