Introduction
Windows Management Instruments (WMI) is a set of extensions to the Windows Driver Model that provides an operating system interface through which instrumented components (either operating system or 3rd party applications) provide information, notification and where applicable commands that can be executed on those components e.g. remotely logging off a user.
WMI plug-in operates by querying a WMI class, each class that has been queried has 0 or more instances associated with it e.g. the Win32_Process class may have 50 instances (where each instance refers to a process running on the machine at the time) and instance 20 may refer to the netprobe.windows.exe process.
There are 2 different modes available; Column mode shows one class and multiple instances, and row mode shows multiple classes with one instance for each class specified.
The metrics produced by WMI can be used in the Geneos Rules (and other gateway features) alongside monitored metric values. These values can help determine almost any issue on a windows machine from running out of hard disk space to the fan speed that cools the CPU. In addition it is possible for in house applications to publish metrics to WMI that can be picked up by the WMI plug-in.
Views
Row View
The row view shows only ever shows 2 columns (the same as the Hardware plug-in). The first column represents a specific attribute name. This can either be the name WMI uses or optionally an alias e.g. Name: "FreePhysicalMemory" Alias: "Available Physical Memory", in this case "Available Physical Memory" would be shown as the column name. The second column represents the value for that attribute e.g.
Row Headline Legend
| Name | Description |
|---|---|
| queryDuration | Specifies how long it took to get the WMI data (measured in milliseconds) (Optional) |
Row Mode Table Legend
| Name | Description |
|---|---|
| <user defined> | User defined representation of a specific class, instance and attribute e.g. FreePhysicalMemory. |
| value | The value associated with the first column e.g. 1,000,000,000 bytes. |
Column View
The column view displays user configured columns for one class e.g. Win32_Process might have Caption, CommandLine and ProcessId configured. In this view all instances are displayed by default unless a restriction is specified. The restriction allows for complex filtering of instances from the view.
Column Mode Headline Legend
| Name | Description |
|---|---|
| queryDuration | Specifies how long it took to get the WMI data (measured in milliseconds) (Optional). |
| class | Name of the class being queried. |
| instances | Number of instances returned for that class. |
| <user defined> | User defined headline variables that represent WMI data. |
Column Mode Table Legend
| Name | Description |
|---|---|
| <user defined> | User defined columns that represent WMI data. |
Classes and Instances
Classes in WMI are templates for grouping a related set of information (known as properties) e.g Win32_LogicalDisk (represent logical disks), Win32_Process (represents processes currently running on windows), Win32_Processor (represents CPUs) etc. For each class that is registered with WMI there are 0 or more instances associated with that class e.g. in the case of Win32_LogicalDisk it may have an instance for C:, D: and E:. Each of these instances can be asked for 0 or more properties that have been specified in the class e.g FreeSpace, FileSystem, DeviceID etc.
Listing Classes and Instances that are available
There is a WMI browsing utility built into every copy of Windows 2000 and upwards called wbemtest.exe. To run this up type wbemtest.exe in a command prompt or run dialog (on a vista machine this is stored in C:\Windows\System32\Wbem\wbemtest.exe).
Listing the Classes
Listing the Properties
This example will use Win32_Process (which should exist on every Windows OS).
Below is an example of how the setup would look after reading information from wbemtest.exe.
Listing Instances
In row mode an instance needs to be specified. To find out which instance should be used click the "Instances" button in the dialog titled "Object editor for Win32_Process".
If the WMI plug-in has to show the caption for the process with an ID 600 (Handle = Process ID) the instance number 5 should be used, this is because it is the 6th item in the list.
To query a different class just close the dialog boxes until the "Query Results" dialog is left.
References
The Microsoft website contains information about all of the classes written for Windows, these can be accessed here.
Restrictions
The WMI plug-in allows the user to specify restrictions on the column mode. Restrictions act to filter out unwanted data in the dataview e.g. only show information about CPU 2 and 4 and are specified using the WMI Query Language (WQL).
WQL is a subset of the American National Standards Institute Structured Query Language (ANSI SQL) - with minor semantic changes. If the user is familiar with SQL then WQL queries should be familiar.
Writing restrictions
Restrictions are written in the form of:
property operator constant
constant operator propertye.g. (Selecting from the Win32_LogicalDisk class)
FileSystem = "NTFS"FileSystem shown above is the property, = is the operator and "NTFS" is the constant. It is important to remember that all string matches are case insensitive so "NTFS", "NtfS" and "ntfs" are all the same as far as WQL is concerned.
Properties
Properties are the named items of information that a particular class can reference e.g.
Properties of class Win32_LogicalDisk
Access
Availability
BlockSize
Caption
Compressed
...
VolumeSerialNumberConstants
Constants are limits that do not change and can be compared against. If the user is specifying a constant it must be the correct type for that property e.g.
FileSystem = "NTFS" - is correct because it requires a string value.
FileSystem = 10 - is not correct because 10 is a number and a string is required.Operators
Operators are the glue that binds a property to a constant. Here is a list of valid operators that can be used:
| Operator | Description |
| = | Equal to |
| < | Less than |
| > | Greater than |
| <= | Less than or equal to |
| >= | Greater than or equal to |
| != or <> | Not equal to |
In addition there are some specific operators: IS, IS NOT, ISA, and LIKE. The IS and IS NOT operators can only be used with NULL e.g. (Selecting from the Win32_LogicalDisk class)
FileSystem IS NULL - Correct
FileSystem IS NOT NULL - Correct
DriveType IS 5 - Incorrect
FileSystem IS NOT "NTFS"LIKE operator
The LIKE operator can be used to match part of a string or a string pattern e.g.
FileSystem LIKE "%FS"This statement will match any string ending in FS. For a complete list of special characters that can be used with LIKE, see the table below.
| Character | Description |
|---|---|
| [ ] | Any one character within the specified range ([a=f]) or set ([abcdef]). |
| ^ | Any one character not within the range ([^a=f]) or set ([^abcdef].) |
| % |
Any string of 0 (zero) or more characters. The following example finds all instances where "Win" is found anywhere in the class name: SELECT * FROM meta_class WHERE __Class LIKE "%Win%"
|
| _ (underscore) | Any one character. Any literal underscore used in the query string must be escaped by placing it inside [] (square brackets). |
To escape the underscore character you will need to place it in square brackets e.g. LIKE "[_][_]%" searches for __ followed by 0 or more characters. Backslash also needs to be escaped by another backslash e.g. LIKE "C:\\Windows\\System32".
Boolean Types
Booleans can be represented as TRUE (or 1) and FALSE (or 0) e.g.
HasDrive = TRUE - Equals true.
HasDrive = 1 - Equals true.
HasDrive != FALSE - Does not equal false.
HasDrive <> 0 - Does not equal false.Examples
Example 1 - Win32_LogicalDisk
(Name = "C:" OR Name = "D:") AND FreeSpace > 2000000000 AND FileSystem = "NTFS"The query only shows logical disks that have the name C and D where their freespace is greater than 2GB (this assumes using 1000bytes to represent a KB) and the filesystem is NTFS.
Example 2 - Win32_Processor
DeviceID = "CPU2" OR DeviceID = "CPU4"The query only shows CPU2 and CPU4 (if they exist) otherwise they won't be populated.
References
Plug-in Configuration
Configuration for the WMI plug-in involves specifying a class and properties (the columns that will be displayed) for the column mode and classes and instances and properties for the row mode. Each part of this configuration is specified in its own section, and is discussed in more detail below.
rowMode
The row mode contains configuration for displaying one property per instance specified. Many instances from different classes can be specified. The view will only show 2 columns: the name of the property and the value of that property.
Mandatory: Yes
rowMode > rows > row > class
The name of the class to view information on e.g. Win32_Process, Win32_LogicalDisk etc.
To find out what classes are supported on system where the netprobe is running refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
rowMode > rows > row > member
The name of the property to display as a column e.g. if the Win32_LogicalDisk has been specified as the class then names could be used like FreeSpace, FileSystem, Name etc.
To find out what properties are supported on for a particular class refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
rowMode > rows > row > instance
The number of the instance of a specific class e.g. Win32_Process instance 12 might map to netprobe.windows.exe. The instance numbering always starts from 0. Using the instance number is most useful when you know a particular instance will exist e.g. Win32_OperatingSystem only has 1 instance so the instance number would always be 0.
Mandatory: Yes (this is mutually exclusive with restriction)
rowMode > rows > row > restriction
Filters out records that do not need to be seen in the view. For more information on specifying restrictions refer here.
Mandatory: Yes (this is mutually exclusive with instance)
rowMode > rows > row > displayName
The alias of the member name specified e.g. if the Win32_Process has been specified as the class and the member has been specified as Handle, then the display name could be set to PID or Process ID to make the column name easier to understand.
Mandatory: No
rowMode > rows > restriction
Filters out records that do not need to be seen in the view. Make sure the filter you apply only returns one instance; otherwise the first instance returned by WMI is used.
Note: WQL does not let you specify a sort order for the data that is returned; you are limited to the sort order imposed on the data by WMI. For more information on specifying restrictions refer here.
Mandatory: No
rowMode > rows > scale
Scale allows a WMI property e.g. WorkingSetSize measured in bytes to be changed to megabytes by dividing by (1024 * 1024). Scale has 2 types of values that can be set, divide and multiply. Divide allows for moving up a unit scale e.g. bytes -> megabytes and multiply allows for moving down a unit scale e.g. megabytes to bytes.
Mandatory: No
columnMode
The column mode contains configuration for displaying one class and all the instances that belong to that class. The class must specify one or more properties that will be displayed as columns in the view. Each instance will display its own value for that column.
Mandatory: Yes
columnMode > columns > class
The name of the class to view information on e.g. Win32_Process, Win32_LogicalDisk etc.
To find out what classes are supported on system where the netprobe is running refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
columnMode > columns > column > member
The name of the property to display as a column e.g. if the Win32_LogicalDisk has been specified as the class then names could be used like FreeSpace, FileSystem, Name etc.
To find out what properties are supported on for a particular class refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
columnMode > columns > column > displayName
The alias of the member name specified e.g. if the Win32_Process has been specified as the class and the member has been specified as Handle, then the display name could be set to PID or Process ID to make the column name easier to understand.
Mandatory: No
columnMode > columns > headlines > headline
The headline setting shows a property of an instance as a headline variable e.g. Percentage of memory free in instance 0 of Win32_OperatingSystem class. Headlines are analogous to the rowMode (they share the same settings).
columnMode > columns > headlines > headline > class
The name of the class to view information on e.g. Win32_Process, Win32_LogicalDisk etc.
To find out what classes are supported on system where the netprobe is running refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
columnMode > columns > headlines > headline > member
The name of the property to display as a column e.g. if the Win32_LogicalDisk has been specified as the class then names could be used like FreeSpace, FileSystem, Name etc.
To find out what properties are supported on for a particular class refer to the instructions here. To view documentation on Microsoft specific classes click here.
Mandatory: Yes
columnMode > columns > headlines > headline > instance
The number of the instance of a specific class e.g. Win32_Process instance 12 might map to netprobe.windows.exe. The instance numbering always starts from 0. Using the instance number is most useful when you know a particular instance will exist e.g. Win32_OperatingSystem only has 1 instance so the instance number would always be 0.
Mandatory: Yes (this is mutually exclusive with restriction)
columnMode > columns > headlines > headline > restriction
Filters out records that do not need to be seen in the view. For more information on specifying restrictions refer here.
Mandatory: Yes (this is mutually exclusive with instance)
columnMode > columns > headline > headline > displayName
The alias of the member name specified e.g. if the Win32_Process has been specified as the class and the member has been specified as Handle, then the display name could be set to PID or Process ID to make the column name easier to understand.
Mandatory: No
columnMode > columns > headlines > headline > scale
Scale allows a WMI property e.g. WorkingSetSize measured in bytes to be changed to megabytes by dividing by (1024 * 1024). Scale has 2 types of values that can be set, divide and multiply. Divide allows for moving up a unit scale e.g. bytes -> megabytes and multiply allows for moving down a unit scale e.g. megabytes to bytes.
Mandatory: No
columnMode > columns > restriction
Filters out records that do not need to be seen in the view. For more information on specifying restrictions refer here.
Mandatory: No
columnMode > columns > scale
Scale allows a WMI property e.g. WorkingSetSize measured in bytes to be changed to megabytes by dividing by (1024 * 1024). Scale has 2 types of values that can be set, divide and multiply. Divide allows for moving up a unit scale e.g. bytes -> megabytes and multiply allows for moving down a unit scale e.g. megabytes to bytes.
Mandatory: No
namespace
Setting this allows the plug-in to query WMI classes on namespaces other than the default. The default namespace used by the plug-in is root\cimv2.
Note: Only local namespaces can be used as the plug-in does not support connection to remote machines via WMI.
Mandatory: No
showQueryDuration
The plug-in does not necessarily have to return all of the values on the first sample as it relies on Windows to supply the data. The query duration is displayed (as headline) in milliseconds. This value can be useful to identify slow running queries e.g. queries with a complex restrictions.
Mandatory: No Default: false
context > providerArchitecture
Setting this allows the WMI plug-in to use a specified non-default WMI provider.
32-bit programs (such as the netprobe) accessing WMI will receive data from 32-bit providers by default. However, it is possible to create WMI instances having only 64-bit provider. To access such WMI instances, this setting can be set to 64. This will instruct the WMI plug-in to try to get data from 64-bit providers.
Mandatory: No
XML Examples
Row Mode
This example shows a configuration of how the row mode works (it mimics some of the information shown in the hardware plug-in).
<sampler name="Row Mode Example">
<sampleInterval>
<data>1</data>
</sampleInterval>
<plugin>
<wmi>
<rowMode>
<rows>
<row>
<class>
<data>Win32_Processor</data>
</class>
<member>
<data>LoadPercentage</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>cpuUtilisation</data>
</displayName>
</row>
<row>
<class>
<data>Win32_NetworkAdapter</data>
</class>
<member>
<data>MACAddress</data>
</member>
<restriction>
<data>Name LIKE "Atheros%"</data>
</restriction>
<displayName>
<data>hostid</data>
</displayName>
</row>
<row>
<class>
<data>Win32_ComputerSystem</data>
</class>
<member>
<data>Name</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>hostname</data>
</displayName>
</row>
<row>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>FreeVirtualMemory</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>memoryIdle</data>
</displayName>
<scale>
<divide>
<data>1024</data>
</divide>
</scale>
</row>
<row>
<class>
<data>Win32_PerfFormattedData_PerfOS_Memory</data>
</class>
<member>
<data>CommittedBytes</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>memoryUse</data>
</displayName>
<scale>
<divide>
<data>1048576</data>
</divide>
</scale>
</row>
<row>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>Caption</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>OS</data>
</displayName>
</row>
<row>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>TotalSwapSpaceSize</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>swapSize</data>
</displayName>
</row>
<row>
<class>
<data>Win32_TimeZone</data>
</class>
<member>
<data>Caption</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>timezone</data>
</displayName>
</row>
<row>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>TotalVisibleMemorySize</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>totalPhysicalMemory</data>
</displayName>
<scale>
<divide>
<data>1024</data>
</divide>
</scale>
</row>
<row>
<class>
<data>Win32_PerfFormattedData_PerfOS_System</data>
</class>
<member>
<data>SystemUpTime</data>
</member>
<instance>
<data>0</data>
</instance>
<displayName>
<data>uptime</data>
</displayName>
<scale>
<divide>
<data>86400</data>
</divide>
</scale>
</row>
</rows>
</rowMode>
</wmi>
</plugin>
</sampler>Column Mode
This example shows a configuration of how the column mode works.
<sampler name="Column Mode Example">
<sampleInterval>
<data>1</data>
</sampleInterval>
<plugin>
<wmi>
<columnMode>
<columns>
<class>
<data>Win32_Process</data>
</class>
<column>
<member>
<data>Caption</data>
</member>
<displayName>
<data>Process Name</data>
</displayName>
</column>
<column>
<member>
<data>CommandLine</data>
</member>
</column>
<column>
<member>
<data>ParentProcessId</data>
</member>
<displayName>
<data>PPID</data>
</displayName>
</column>
<column>
<member>
<data>ProcessId</data>
</member>
<displayName>
<data>PID</data>
</displayName>
</column>
<column>
<member>
<data>ThreadCount</data>
</member>
</column>
<column>
<member>
<data>WorkingSetSize</data>
</member>
<scale>
<divide>
<data>1048576</data>
</divide>
</scale>
</column>
<column>
<member>
<data>CreationDate</data>
</member>
</column>
<headlines>
<headline>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>FreePhysicalMemory</data>
</member>
<instance>
<data>0</data>
</instance>
<scale>
<divide>
<data>1048576</data>
</divide>
</scale>
</headline>
<headline>
<class>
<data>Win32_OperatingSystem</data>
</class>
<member>
<data>InstallDate</data>
</member>
<instance>
<data>0</data>
</instance>
</headline>
</headlines>
<restriction>
<data>CommandLine LIKE "C:\\Windows%"</data>
</restriction>
</columns>
</columnMode>
<showQueryDuration>true</showQueryDuration>
</wmi>
</plugin>
<debug>
<setting>ON</setting>
</debug>
</sampler>