|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | EXAMPLE | SEE ALSO | COLOPHON |
|
|
|
PMNOTIFYTHROTTLE(3) Library Functions Manual PMNOTIFYTHROTTLE(3)
__pmNotifyThrottle, __pmResetNotifyThrottle - control diagnostic
output message `flooding''
#include <pcp/pmapi.h>
#include <pcp/libpcp.h>
int __pmNotifyThrottle(char *key, int subkey);
int __pmResetNotifyThrottle(char *key, int subkey);
cc ... -lpcp
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.
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.
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);
}
}
PMAPI(3) and pmOpenLog(3).
This page is part of the PCP (Performance Co-Pilot) project. In‐
formation about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) 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 man-pages@man7.org
Performance Co-Pilot PCP PMNOTIFYTHROTTLE(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|