Crate throttled_tracing

Expand description

Periodic and throttled logging macros for the tracing ecosystem.

This crate provides macros that extend tracing with rate-limited logging capabilities:

*_once! - Log only the first time the macro is reached
*_every!(duration, ...) - Log at most once per specified duration
*_every_n!(n, ...) - Log every N occurrences
*_first_n!(n, ...) - Log only the first N occurrences
*_backoff!(initial, max, ...) - Log with exponential backoff
*_on_change!(value, ...) - Log only when the tracked value changes
*_once_per_value!(key, ...) - Log once per unique key value
*_sample!(probability, ...) - Log with probability sampling

§Examples

use throttled_tracing::{info_once, debug_every, warn_every_n};
use std::time::Duration;

fn process_item(item: u32) {
    // Only logs the first time this line is reached
    info_once!("Processing started");

    // Logs at most once per second
    debug_every!(Duration::from_secs(1), "Processing item {}", item);

    // Logs every 100th call
    warn_every_n!(100, "Processed {} items so far", item);
}

use throttled_tracing::{error_backoff, info_on_change, debug_once_per_value, trace_sample};
use std::time::Duration;

fn handle_error(err: &str) {
    // Exponential backoff: logs at 1s, 2s, 4s, 8s... up to 60s
    error_backoff!(Duration::from_secs(1), Duration::from_secs(60), "Error: {}", err);
}

fn monitor_status(status: u32) {
    // Only logs when status changes
    info_on_change!(status, "Status changed to {}", status);
}

fn process_user(user_id: u64) {
    // Logs once per unique user_id
    debug_once_per_value!(user_id, "First time seeing user {}", user_id);
}

fn high_volume_operation() {
    // Logs ~1% of calls
    trace_sample!(0.01, "Sampled operation");
}

Re-exports§

pub use parking_lot;
pub use tracing;
pub use fastrand;

Macros§

debug_backoff: Logs a message at the DEBUG level with exponential backoff. Starts at initial interval, doubles after each log, caps at max.
debug_every: Logs a message at the DEBUG level at most once per specified duration.
debug_every_n: Logs a message at the DEBUG level every N occurrences.
debug_first_n: Logs a message at the DEBUG level only for the first N occurrences.
debug_on_change: Logs a message at the DEBUG level only when the tracked value changes.
debug_once: Logs a message at the DEBUG level only once.
debug_once_per_value: Logs a message at the DEBUG level once per unique value.
debug_sample: Logs a message at the DEBUG level with the given probability (0.0 to 1.0).
error_backoff: Logs a message at the ERROR level with exponential backoff. Starts at initial interval, doubles after each log, caps at max.
error_every: Logs a message at the ERROR level at most once per specified duration.
error_every_n: Logs a message at the ERROR level every N occurrences.
error_first_n: Logs a message at the ERROR level only for the first N occurrences.
error_on_change: Logs a message at the ERROR level only when the tracked value changes.
error_once: Logs a message at the ERROR level only once.
error_once_per_value: Logs a message at the ERROR level once per unique value.
error_sample: Logs a message at the ERROR level with the given probability (0.0 to 1.0).
info_backoff: Logs a message at the INFO level with exponential backoff. Starts at initial interval, doubles after each log, caps at max.
info_every: Logs a message at the INFO level at most once per specified duration.
info_every_n: Logs a message at the INFO level every N occurrences.
info_first_n: Logs a message at the INFO level only for the first N occurrences.
info_on_change: Logs a message at the INFO level only when the tracked value changes.
info_once: Logs a message at the INFO level only once.
info_once_per_value: Logs a message at the INFO level once per unique value.
info_sample: Logs a message at the INFO level with the given probability (0.0 to 1.0).
trace_backoff: Logs a message at the TRACE level with exponential backoff. Starts at initial interval, doubles after each log, caps at max.
trace_every: Logs a message at the TRACE level at most once per specified duration.
trace_every_n: Logs a message at the TRACE level every N occurrences.
trace_first_n: Logs a message at the TRACE level only for the first N occurrences.
trace_on_change: Logs a message at the TRACE level only when the tracked value changes.
trace_once: Logs a message at the TRACE level only once.
trace_once_per_value: Logs a message at the TRACE level once per unique value.
trace_sample: Logs a message at the TRACE level with the given probability (0.0 to 1.0).
warn_backoff: Logs a message at the WARN level with exponential backoff. Starts at initial interval, doubles after each log, caps at max.
warn_every: Logs a message at the WARN level at most once per specified duration.
warn_every_n: Logs a message at the WARN level every N occurrences.
warn_first_n: Logs a message at the WARN level only for the first N occurrences.
warn_on_change: Logs a message at the WARN level only when the tracked value changes.
warn_once: Logs a message at the WARN level only once.
warn_once_per_value: Logs a message at the WARN level once per unique value.
warn_sample: Logs a message at the WARN level with the given probability (0.0 to 1.0).

Structs§

BackoffState: State for exponential backoff logging.
CountState: State for count-based throttling.
FirstNState: State for logging only the first N occurrences.
OnChangeState: State for logging only when a value changes. Uses hash comparison, so values must implement Hash.
OncePerValueState: State for logging once per unique value. Uses hash-based deduplication, so values must implement Hash. Note: Memory grows with each unique value seen.
OnceState: State for one-time logging.
SampleState: State for probabilistic sampling.
ThrottleState: State for duration-based throttling.

Crate throttled_tracing

Crate throttled_tracing Copy item path

§Examples

Re-exports§

Macros§

Structs§

Crate throttled_tracing