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