Dictionary based parameters and factory settings

When to use dictionary based parameters

While for simple checks like a CPU check for some appliance a check parameter like a pair of integers - (80, 90) - is sufficient, more complex checks need a more flexible way of defining parameters.

Such an example is the disk-free-check df. In recent versions of Check_MK that check offers a dictionary based way to specify parameters. In that case the parameter to a check is a dictionary with key/value pairs like:

{ "levels" : (80, 90), "trend_range" : 48, "trend_mb" : (200, 400), }

... or, if you indent this a bit more nicely:

{
    "levels"      : (80, 90),
    "trend_range" : 48,
    "trend_mb"    : (200, 400),
}

For the user this has the following advantages:

• It is easier to write and read as a tuple like (80, 90, 48, 200, 400, None, ...).
• It allows to specify only some of the keys and use the default settings for others.
• It allows to override only some keys when using check_parameters.

As a check developer it is your task to decide, whether a simple scheme like (80, 90) is sufficient or you want to use the flexibility of a dictionary. Please have in mind, however, that it is hard to change the format of the check parameters later while being compatible with older versions of a check.

How to write dictionary based checks

Check_MK supports you in writing dictionary based checks. The version 1.1.11i2 introduces a new concept called factory settings. Let's assume your check is named foo. When defining your default variable foo_default_levels you do not create that variable in your check, but instead add its name to a builtin dictionary called check_default_levels:

check_default_levels["foo"] = "foo_default_levels"

The default values of that variable are then defined in the dictionary factory_settings:

factory_settings["foo_default_levels"] = {
    "heat_levels"    : (600, 800),
    "trend"          : 0.5,
    "allowed_states" : [ 0, 2, 3, 6, 8 ],
}

It is also possible to leave some keys out. The default value for those is is "unset": the particular aspect is not being checked in that case.

That's all! When writing your check function, you can always rely on Check_MK making sure that params is a valid dictionary containing all of the keys that have been defined in factory_settings, with at least some setting. Some might have been set by inventory, some by the user, some might still have the factory settings. Using the parameters is as simply as doing dictionary lookups where needed:

def check_foo(item, params, info):
    ...
    if state not in params["allowed_states"]:
        ...

Note (1): The code of the check must never access factory_settings directly. Believe me! Check_MK will make sure they are reflected in params.

Note (2): It is not uncommon that several checks share the same default variable. This makes sense if the checks do practically the same, but just parse different types of input. In that case check_default_levels needs to be defined for each check, but the factory_settings definition needs only to be done once. You can put it into an include file commonly used by all those checks.

Note (3): Keys that are not set in factory_settings[...] might be unset in params. Your check could needs to tolerance their absence. Either check if they are present or work with params.get("foo"), which returns None in case the key is not set.

Inventory

When using dictionary based checks, the inventory function does not longer need to insert the name of the defaults variable as check parameter. Instead it simply inserts an empty dictionary ({}):

def inventory_foo(checkname, info):
    inventory = []
    for line in info:
        # some other stuff...
        inventory.append( (some_item, {}) )
    return inventory

Some checks determine the current state of something and code that into the check parameters at inventory time. When using factory_settings this is easy. You can simply specify a (usually partially filled) parameter dictionary as check parameter. Check_MK will make sure that:

• this is correctly merged with the factory settings,
• the user can partly override keys of the parameters without losing the values of the inventory.

An example code could look like this:

def inventory_foo(checkname, info):
    inventory = []
    for line in info:
        # some other stuff...
        inventory.append(({ "state": line[8], "heat" : line[7] }, line[1]))
    return inventory

Dictionary based parameters without default values

If you cannot think of any sensible default parameters for your check then you can make use of dictionary based parameters without defining factory settings. Simply let the inventory put the empty dictionary {} as check parameter.

The check then treat params as a dictionary with optional entries. The merging of the dictionary by the rule algorithm works nevertheless.