__pmnotifythrottle(3) — Linux manual page

NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON

PMNOTIFYTHROTTLE(3)     Library Functions Manual     PMNOTIFYTHROTTLE(3)

NAME         top

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

C SYNOPSIS         top

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

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

       cc ... -lpcp

CAVEAT         top

       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         top

       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         top

       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         top

       PMAPI(3) and pmOpenLog(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

Performance Co-Pilot               PCP               PMNOTIFYTHROTTLE(3)