Struct RateLimiterMetrics 

pub struct RateLimiterMetrics {
    pub total_acquired: u64,
    pub total_rejected: u64,
    pub total_refills: u64,
    pub current_tokens: u64,
    pub max_tokens: u64,
    pub consecutive_rejections: u32,
    pub max_wait_time_ns: u64,
    pub pressure_ratio: f64,
}

Metrics and health monitoring for observability Comprehensive metrics for rate limiter performance analysis.

This struct provides a snapshot of all important rate limiter metrics, allowing you to monitor performance, detect issues, and make informed decisions about capacity planning.

Key Metrics Explained

Success Metrics

• total_acquired: Successfully processed requests
• total_rejected: Requests that were rate limited
• success_rate: Percentage of successful requests

Capacity Metrics

• current_tokens: Available capacity right now
• max_tokens: Maximum possible capacity
• utilization: How much of the capacity is being used

Pressure Indicators

• consecutive_rejections: Recent rejection streak (high = pressure)
• pressure_ratio: Overall rejection ratio
• max_wait_time_ns: Longest wait observed

Example Usage

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
// ... use the limiter ...

let metrics = limiter.metrics();

// Check health
if metrics.is_under_pressure() {
    println!("⚠️ System under pressure!");
    println!("Success rate: {:.1}%", metrics.success_rate() * 100.0);
}

// Display comprehensive report
println!("{}", metrics.summary());

Fields

total_acquired: u64

Total number of tokens successfully acquired. This represents the number of allowed requests.

total_rejected: u64

Total number of token acquisition attempts that were rejected. This represents the number of rate-limited requests.

total_refills: u64

Total number of refill operations performed. High numbers indicate the limiter has been active for a while.

current_tokens: u64

Current number of available tokens in the bucket. This is the immediate capacity available.

max_tokens: u64

Maximum capacity of the token bucket. This is the burst limit configured for the limiter.

consecutive_rejections: u32

Number of consecutive rejections without a successful acquisition. High values (>10) indicate sustained pressure.

max_wait_time_ns: u64

Maximum wait time observed in nanoseconds. Useful for identifying contention issues.

pressure_ratio: f64

Ratio of rejected requests to total requests (0.0 to 1.0). Values above 0.3 indicate significant pressure.

Implementations

impl RateLimiterMetrics

pub fn success_rate(&self) -> f64

Calculates the success rate of token acquisitions.

Returns

A value between 0.0 and 1.0, where:

• 1.0 = 100% success (no rejections)
• 0.5 = 50% success (half rejected)
• 0.0 = 0% success (all rejected)

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
if metrics.success_rate() < 0.8 {
    println!("Warning: High rejection rate!");
}

pub fn rejection_rate(&self) -> f64

Calculates the rejection rate (inverse of success rate).

Returns

A value between 0.0 and 1.0 representing the fraction of rejected requests.

pub fn is_under_pressure(&self) -> bool

Determines if the rate limiter is under immediate pressure.

Immediate pressure means:

• Success rate below 50%, OR
• No tokens currently available

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
if metrics.is_under_pressure() {
    // Consider backing off or queueing requests
}

pub fn utilization(&self) -> f64

Calculates the current utilization of the token bucket.

Utilization shows how much of the capacity is being used:

• 0.0 = Bucket is full (no usage)
• 0.5 = Half capacity used
• 1.0 = Bucket is empty (full usage)

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
if metrics.utilization() > 0.9 {
    println!("Running at high utilization!");
}

pub fn availability_percentage(&self) -> f64

Returns the percentage of available tokens.

This is the inverse of utilization, showing remaining capacity:

• 100% = Bucket is full
• 50% = Half capacity available
• 0% = No tokens available

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
println!("Available capacity: {:.1}%", metrics.availability_percentage());

pub fn is_under_sustained_pressure(&self) -> bool

Determines if the rate limiter is under sustained pressure.

Sustained pressure indicates ongoing high demand that exceeds capacity. This is detected when:

• More than 10 consecutive rejections, OR
• Overall rejection ratio above 30%

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
if metrics.is_under_sustained_pressure() {
    // Consider scaling up capacity or implementing backpressure
    println!("System needs intervention!");
}

pub fn max_wait_time_us(&self) -> f64

Returns the maximum wait time in microseconds.

Converts nanoseconds to microseconds for easier reading.

pub fn max_wait_time_ms(&self) -> f64

Returns the maximum wait time in milliseconds.

Converts nanoseconds to milliseconds for easier reading.

Example

use rater::RateLimiter;

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
if metrics.max_wait_time_ms() > 10.0 {
    println!("High contention detected: {:.2}ms max wait",
             metrics.max_wait_time_ms());
}

pub fn total_requests(&self) -> u64

Returns the total number of requests (acquired + rejected).

pub fn health_status(&self) -> HealthStatus

Determines the health status of the rate limiter.

Health status provides a quick assessment of the limiter’s state:

• Healthy: Operating normally
• Degraded: Under some pressure but functional
• Critical: Severe pressure, intervention needed

Example

use rater::{HealthStatus, RateLimiter};

let limiter = RateLimiter::new(100, 10);
let metrics = limiter.metrics();
match metrics.health_status() {
    HealthStatus::Healthy => println!("✅ All good"),
    HealthStatus::Degraded => println!("⚠️ Monitor closely"),
    HealthStatus::Critical => println!("🔴 Take action!"),
}

pub fn summary(&self) -> String

Generates a human-readable summary of the metrics.

This provides a comprehensive report suitable for logging or display.

Example Output

RateLimiter Metrics:
├─ Performance:
│  ├─ Success Rate: 85.50%
│  ├─ Rejection Rate: 14.50%
│  └─ Max Wait Time: 1.234ms
├─ Capacity:
│  ├─ Available Tokens: 75/100
│  ├─ Utilization: 25.00%
│  └─ Availability: 75.00%
└─ Health:
   ├─ Status: Healthy
   └─ Under Pressure: false

Trait Implementations

impl Clone for RateLimiterMetrics

fn clone(&self) -> RateLimiterMetrics

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RateLimiterMetrics

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RateLimiterMetrics

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.