|
HTML rendering created 2024-06-26 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
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.
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);
}
}
PMAPI(3) and pmOpenLog(3).
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)
|
HTML rendering created 2024-06-26 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. |
|