Rate-limited logging for frequent events

Often we want to tell the user about an event that is undesirable when it happens, but which can happen very frequently. In that case, we don't want to log "There was a problem!" a thousand times per hour. Instead, we'd like our logs to look more like "connecting to the guard X: error (problem occurred 1310/2000 times in the last hour)"

This crate is part of arti, and is not adapted for use outside of it: it assumes that your logging system is tracing, and that you are using tor_rtcompat for your asynchronous runtime.

Setup

Before you can use this crate, you need to call install_runtime, or messages won't be collected.

Example

use tor_log_ratelim::log_ratelim;
# use std::num::ParseIntError;
pub fn parse_u8(source: &str, s: &str) -> u8 {
    let r: Result<u8, ParseIntError> = s.parse();
    log_ratelim!(
        // The activity we were performing
        "parsing an integer from {}", source;
        // A Result to decide whether it succeeded 
        r; 
        // An error message to report on failure, with rate limiting,
        // after some time has elapsed.
        // The error itself is always reported.
        Err(_) => WARN, "Had to use default";
        // A success message to report (without rate limiting)
        // on every success.
        Ok(v) => TRACE, "Got {}", v;
    );
    r.unwrap_or(0)
}

The above example might produce WARN outputs more or less like these:

WARN: Parsing an integer from cache: error (Problem occurred 7/10 times in the last minute): Had to use default: invalid digit found in string"
WARN: Parsing an integer from cache: error (Problem occurred 81/92 times in the last 5 minutes): Had to use default: number too large to fit in target type"
WARN: Parsing an integer from cache: now working (Problem occurred 0/106 times in the last 5 minutes)

and TRACE outputs like these:

TRACE: Parsing an integer from cache: Got 7
TRACE: Parsing an integer from cache: Got 14
TRACE: Parsing an integer from the network: Got 2

For more information on log_ratelim!, and simpler ways to invoke it, see its documentation.