Skip to content

Developer Guide: New-IcingaCheck

Below you will find a list of functions and detailed descriptions including use cases for Cmdlets and features the PowerShell Framework provides.

Type Return Value Description
Cmdlet PowerShell Object Check Object containing values and handling warning / error states

The IcingaCheck is the basic start point for determining on how a certain value is performing. Checks will provide a bunch of internal commands within the PowerShell Object to analyse a value and get the Icinga result Ok, Warning, Critical including performance metrics.

Checks are always used within Check Plugins to have a standardised method for properly handling the input.

It will be used like in this example:

$IcingaCheck = New-IcingaCheck -Name 'My Check' -Value 25 -Unit '%';

You will have to provide a Name for each check which must be unique within each Check Plugin. This will make it easier to differentiate between checks for results. The Value is mandatory as this will be the basis for each single check to fetch the actual status.

For performance metrics you can provide a Unit to ensure your graphing is displaying values as the should be

Arguments

Argument Input Mandatory Description
Name String * The unique name of each check within a plugin. Will be display in the check output.
Value Object * The value all comparison is done with. In general this should be a Numeric or String value
Unit Units Specify the unit for a value to display graph properly
Minimum String The minimum value which is displayed on your graphs
Maximum String The maximum value which is displayed on your graphs
ObjectExists Bool If you are using values coming from objects, like Services, you can use this argument to determin if the object itself exist or not. In case it doesn’t, you will receive a proper output on the check result
Translation Hashtable In case you want to map values to certain descriptions, you can place a hashtable at this argument which will then map the value to the description on the check result. For example this would apply to service running states
LabelName String Allows to override the default label name generated based on the -Name argument to a custom name. Please ensure to remove any special characters manually, as the name set here is the exact name for the label
NoPerfData Switch Disables Performance Data output for this check object

Units

Unit Name Description
% Percentage The input value is a percentage value
s Seconds The input is indicated as time seconds
ms Milliseconds The input is indicated as time in milliseconds
us Microseconds The input is indicated as time in microseconds
B Bytes The input is indicated as quantity in bytes
KB Kilobytes The input is indicated as quantity in Kilobytes
MB Megabytes The input is indicated as quantity in Megabytes
GB Gigabytes The input is indicated as quantity in Gigabytes
TB Terabytes The input is indicated as quantity in Terabytes
c Counter A continues counter increasing values over time

Object Functions

The New-IcingaCheck Cmdlet will return a custom PowerShell object which provides a bunch of functions to easier manage the handling of the output.

Please note that most of the listed functions below will return itself as object, which means you will have to drop the content with | Out-Null after calling them.

Wrong

$IcingaCheck.WarnOutOfRange(10)

Correct

$IcingaCheck.WarnOutOfRange(10) | Out-Null

Nested functions

An example for a nested function call could be this

$IcingaCheck.WarnOutOfRange(10).CritOutOfRange(20) | Out-Null

Functions

For most parts it is recommended to use the OutOfRange functions for warning and critical checks as the user is able to dynamicly set the range with the arguments of the plugins. For string values the Like and Match functions should be used.

Function Parameters Description Example
WarnOutOfRange Warning This will make use of the Icinga Threshhold handling, like 10, ~:10, @10:20 and properly return the correct ok / warning state of the plugin $IcingaCheck.WarnOutOfRange(10)
CritOutOfRange Critial This will make use of the Icinga Threshhold handling, like 10, ~:10, @10:20 and properly return the correct ok / critical state of the plugin $IcingaCheck.CritOutOfRange(10)
WarnIfLike Warning Will return warning in case the input is like the value $IcingaCheck.WarnIfLike(‘*running*‘)
WarnIfNotLike Warning Will return warning in case the input is not like the value $IcingaCheck.WarnIfNotLike(‘*running*‘)
WarnIfMatch Warning Will return warning in case the input is matching the value $IcingaCheck.WarnIfMatch(‘running’)
WarnIfNotMatch Warning Will return warning in case the input is not matching the value $IcingaCheck.WarnIfNotMatch(‘running’)
CritIfLike Critial Will return critical in case the input is like the value $IcingaCheck.CritIfLike(‘*running*‘)
CritIfNotLike Critial Will return critical in case the input is not like the value $IcingaCheck.CritIfNotLike(‘*running*‘)
CritIfMatch Critial Will return critical in case the input is matching the value $IcingaCheck.CritIfMatch(‘running’)
CritIfNotMatch Critial Will return critical in case the input is not matching the value $IcingaCheck.CritIfNotMatch(‘running’)

All other functions

Function Parameters Description Example
WarnIfBetweenAndEqual Min, Max Will return warning in case the input is between or equal the min and max value $IcingaCheck.WarnIfBetweenAndEqual(10, 20)
WarnIfBetween Min, Max Will return warning in case the input is between the min and max value $IcingaCheck.WarnIfBetween(10, 20)
WarnIfLowerThan Warning Will return warning in case the input is lower than the value $IcingaCheck.WarnIfLowerThan(10)
WarnIfLowerEqualThan Warning Will return warning in case the input is lower or equal than the value $IcingaCheck.WarnIfLowerEqualThan(10)
WarnIfGreaterThan Warning Will return warning in case the input is greater than the value $IcingaCheck.WarnIfGreaterThan(10)
WarnIfGreaterEqualThan Warning Will return warning in case the input is greater or equal than the value $IcingaCheck.WarnIfGreaterEqualThan(10)
CritIfBetweenAndEqual Min, Max Will return critical in case the input is between or equal the min and max value $IcingaCheck.CritIfBetweenAndEqual(10, 20)
CritIfBetween Min, Max Will return critical in case the input is between the min and max value $IcingaCheck.CritIfBetween(10, 20)
CritIfLowerThan Critial Will return critical in case the input is lower than the value $IcingaCheck.CritIfLowerThan(10)
CritIfLowerEqualThan Critial Will return critical in case the input is lower or equal than the value $IcingaCheck.CritIfLowerEqualThan(10)
CritIfGreaterThan Critial Will return critical in case the input is greater than the value $IcingaCheck.CritIfGreaterThan(10)
CritIfGreaterEqualThan Critial Will return critical in case the input is greater or equal than the value $IcingaCheck.CritIfGreaterEqualThan(10)

Examples

Example 1

Simple check item which will return critical as the value is 37 and we want throw warning above 20 and critical above 35

$IcingaCheck = New-IcingaCheck -Name 'My Check' -Value 37 -Unit '%';
$IcingaCheck.WarnOutOfRange(20).CritOutOfRange(35) | Out-Null;

Example 2

Check item with ObjectExists argument including Translation. As the input status 4 is an integer, we will convert the status to the string value Running and use the Translation argument to properly print the output in human readable strings

$Service         = Get-IcingaServices -Service 'icinga2';
$ConvertedStatus = ConvertTo-ServiceStatusCode -Status 4;
$StatusRaw       = $Service.Values.configuration.Status.raw;

$IcingaCheck = New-IcingaCheck -Name 'Icinga 2 Service' -Value $StatusRaw -ObjectExists $Service -Translation $ProviderEnums.ServiceStatusName;
$IcingaCheck.CritIfNotMatch($ConvertedStatus) | Out-Null;

Output after parsed into New-IcingaCheckResult

[CRITICAL]: Icinga 2 Service Stopped is not matching Running