Developer Guide: Fetching Cim-Instance and Wmi-Object data¶

The easiest way of fetching certain information about a Windows system is by using the PowerShell cmdlet Get-WmiObject or Get-CimInstance. Both functions provide a huge amount of data for monitoring the host.

How ever, as the Icinga for Windows solutions is trying to keep the effort as low as possible including the error handling we implemented a wrapper function to handle most common issues.

The Problem with WMI and CIM calls¶

In general it doesn’t matter if you are using Get-WmiObject or Get-CimInstance to fetch data. How ever, the return output could vary a little including on how to loop certain content.

Get-CimInstance Win32_ComputerSystem;

Name     PrimaryOwnerName Domain TotalPhysicalMemory Model   Manufacturer
----     ---------------- ------ ------------------- -----   ------------
testhost icinga           ICINGA 34304962560         MS-7C35 Micro-Star International Co., Ltd.

Get-WmiObject Win32_ComputerSystem;

Domain              : ICINGA
Manufacturer        : Micro-Star International Co., Ltd.
Model               : MS-7C35
Name                : testhost
PrimaryOwnerName    : icinga
TotalPhysicalMemory : 34304962560

As long as we are not running in any kind of error, the fetching is straight forward. Once we run how ever into errors we will have to handle these and ensure our plugins are executed properly. One example would either be a permission error or a not found class. This could look like this

Use-Icinga;
Invoke-IcingaCheckMemory;

Get-CimInstance: Access denied
RuntimeException: Attempted to divide by zero.
MethodInvocationException: Exception calling "Format" with "2" argument(s): "Value cannot be null.
Parameter name: args"
[OK] Check package "Memory Usage"
| 'memory_percent_used'=%;;;0;100 'used_bytes'=0B;;;0

Now of course we do not want to have some sort of error within our plugin output or corrupted data to work with. The goal would be to achieve something like this:

[UNKNOWN]: Icinga Permission Error was thrown: CimInstance: Win32_PhysicalMemory

The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch "root/cimv2" and add the permission "Remote enable".

Easy fetching of data¶

To ensure the above mentioned functionality is made easy, we added the wrapper function Get-IcingaWindowsInformation. This function will by default use the Get-CimInstance Cmdlet and as fallback Get-WmiObject:

Get-IcingaWindowsInformation Win32_ComputerSystem;

Name     PrimaryOwnerName Domain TotalPhysicalMemory Model   Manufacturer
----     ---------------- ------ ------------------- -----   ------------
testhost icinga           ICINGA 34304962560         MS-7C35 Micro-Star International Co., Ltd.

If required you can also force the usage of WMI over CIM:

Get-IcingaWindowsInformation Win32_ComputerSystem -ForceWMI;

Domain              : ICINGA
Manufacturer        : Micro-Star International Co., Ltd.
Model               : MS-7C35
Name                : testhost
PrimaryOwnerName    : icinga
TotalPhysicalMemory : 34304962560

Build-in error handling¶

In addition to make fetching itself easier we also ensure a proper standardized error handling. Instead of throwing an exception the developer has to take care of

Get-CimInstance Win32_NotExistingClass;

Get-CimInstance : Invalid Class
Line:1 Symbol:1
+ Get-CimInstance Win32_NotExistingClass
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : MetadataError: (root\cimv2:Win32_NotExistingClass:String) [Get-CimInstance], CimException
    + FullyQualifiedErrorId : HRESULT 0x80041010,Microsoft.Management.Infrastructure.CimCmdlets.GetCimInstanceCommand

we exit the plugin call and output a proper status information including the correct status code:

Use-Icinga;
Get-IcingaWindowsInformation Win32_NotExistingClass;

[UNKNOWN]: Icinga Invalid Input Error was thrown: CimClassNameUnknown: Win32_NotExistingClass

The provided class name you try to fetch with Get-CimInstance is not known on this system.

Usage of filters¶

As for Get-CimInstance or Get-WmiObject you can also use the -Filter argument to search for certain content within the return output and only return specific content:

Use-Icinga;
Get-IcingaWindowsInformation Win32_Service -Filter "Name='icinga2'";

ProcessId Name    StartMode State   Status ExitCode
--------- ----    --------- -----   ------ --------
14360     icinga2 Automatic Running OK     0