Werk #1723: New check API function get_rate() as more intelligent replacement for get_counter()

The function get_counter() is now deprecated in the programming of checks. There is a new function called get_rate() that should be used as a replacement.

def get_rate(countername, this_time, this_val, allow_negative=False, onwrap=SKIP):
    ...
    return rate

The call syntax is almostthe same - just with the new optional parameter onwrap. Important however: now just the rate (counter steps per second) is being returned. The formerly additional return value timedif has been dropped since it is of no real use. So the return type has changed from tuple to float.

The most imporant change - however - is in the handling of counter wraps. A counter wrap happens in three situations:

• When the counter is seen for the first time (initialization)
• When the previous value of the counter is larger than the new one
• When the time difference since the last counter update was less than one second

Wraps usually happen when a device reboots or when the valid range of the counter is exceeded and it wraps through again to zero.

The old function get_counter() used to raise an exception of type MKCounterWrapped. This exception was handeld by the main core of Check_MK, which skipped that check for one cycle. The problem were checks with more than one counter: at the point of initialization the code of the check wasaborted after the first of these counters had been initialized. If you had 10 counters, you would need 10 check cycles until the first time a check result would be returned. So in order to avoid that the check had to catch the MKCounterWrapped itself and handle this situation - very ugly.

The new function get_rate implements a different approach. Per default no exception is raised in case of a counter wrap, but simply the value 0.00 is being returned. But Check_MK keeps record of this wrap event. After the check function has completed (and all counters are handled), Check_MK creates one final MKCounterWrapped exception, so that the (invalid) check result is being skipped as it should be. This way the check programmers' burden is a reduced a bit because now even if the check has several counters he does not need to catch counter wraps.

In order to give the check more flexibility there are two other behaviours, that can be selected by the optional argument onwrap:

Note: Using ZERO is generally not a good idea. This can make a service jump from CRIT to OK from now and then and generate bogus notifications.

To the list of all Werks