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).

Performance Co-Pilot                                   PCP                                   PMNOTIFYTHROTTLE(3)