NAME¶

__pmNotifyThrottle, __pmResetNotifyThrottle - control diagnostic output message `flooding''

C SYNOPSIS¶

#include <pcp/pmapi.h>
#include <pcp/libpcp.h>

int __pmNotifyThrottle(char *key, int subkey);
int __pmResetNotifyThrottle(char *key, int subkey);

cc ... -lpcp

CAVEAT¶

This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future.

DESCRIPTION¶

When the same error condition occurs over and over, like in a DoS attack, or catastrophic networking failure, or bad system configuration, or software botch, there is a risk that a PCP application could generate a large number of identical diagnostic messages, filling up a log file and hence a filesystem. __pmNotifyThrottle is intended to be used as a guard that can detect repeated calls for the same error condition and allow the caller to stop issuing messages when repeated badness happens.

The error condition is identified by key and subkey, and the most common use case would be for these to be __FILE__ and __LINE__ at the point where __pmNotifyThrottle is called.

For each unique key and subkey pair __pmNotifyThrottle maintains a count of the number of times it has been called in the life of the calling process.

The return values are 0 if the throttle limit for key and subkey has not been reached, else 1 if the throttle limit has been reached, else 2 if the throttle limit has been exceeded.

The same throttle limit as applied across all error conditions and set by the environment variable PCP_NOTIFY_THROTTLE else a default of 10 if the environment variable is not set, although this can be subsequently modified by calling __pmResetNotifyThrottle.

__pmResetNotifyThrottle may be used to reset the counter for an error condition to zero, so that diagnostic output can be resumed if the caller determines it is safe to do so. If limit is greater than zero then the limit for the error condition is also reset, otherwise the limit is unchanged.

Calling __pmResetNotifyThrottle with a key value of NULL will reset the counters (and possibly limits) for all error conditions, and in this case if limit is greater than zero the default limit for any new error conditions is also set (over-riding the default setting or the value initialized from the PCP_NOTIFY_THROTTLE environment variable).

__pmResetNotifyThrottle will return -ENOENT if key and subkey does not match an existing error condition, else the return value is the sum of the number of times the limit has been exceeded across all selected error conditions.

EXAMPLE¶

The following is a simple throttle that stops reporting errors after 10 trips.

if ((sts = __pmNotifyThrottle(__FILE__, __LINE__)) < 2) {


    fprintf(stderr, "Some error message\n");


    if (sts == 1)
	fprintf(stderr, "[further messages will be suppressed]\n");
}

The more sophisticated example below throttles messages, but enables them again after 10 minutes.

int    lineno;
time_t first_throttle;
...
lineno = __LINE__ + 1;
if ((sts = __pmNotifyThrottle(__FILE__, lineno)) < 2) {


    pmNotifyErr(LOG_INFO, "Some error message");


    if (sts == 1) {
	first_throttle = time(NULL);
	pmNotifyErr(LOG_INFO, "[further messages will be suppressed]");


    }
}
else if (sts == 2) {


    if (time(NULL) - first_throttle >= 600) {
	sts = __pmResetNotifyThrottle(__FILE__, lineno, -1);
	pmNotifyErr(LOG_INFO, "[%d messages were suppressed]", sts);


    }
}

SEE ALSO¶

PMAPI(3) and pmOpenLog(3).