# __pmnotifythrottle

## 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 configu‐
           ration,  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 re‐
           set 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** en‐
           vironment 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 af‐
           ter 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  en‐
           ables 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);
                   }
               }
    


* * *