Crate statman

statman: A global manager of atomic statistics

Stats Manager

Individual statistics are managed by a Stats instance. Most use-cases will utilize the global instance by calling Stats::global, however multiple Stats managers may be instantiated using Stats::new().

Individual stats are managed by name. Stats of the same name and type will update the same underyling value.

Stat impls

All stats are produced in an Arc so they may be written to by multiple thread.

• Counter: A counter backed by an std::sync::atomic::AtomicU64
• GaugeF64: A gauge backed by an atomic_float::AtomicF64
• GaugeI64: A gauge backed by an std::sync::atomic::AtomicI64
• Histogram: An hdrhistogram encapsulated with a spin lock.
• Set: A set of strings backed by an scc::HashSet

Scheduler

Stats is a manager of named stats and does not do any scheduling by default. Users may elect to schedule their own calls to Stats::flush or use the scheduler module.

Resetting Stats

By default, stats do not reset between calls to flush. This behavior can be overwritten for individual stats using set_reset_on_flush. It can be overwritten globally using Stats set_default_reset_on_flush_for_* functions.

Example

use std::{
    sync::{
        atomic::{AtomicBool, Ordering},
        Arc,
    },
    thread,
    time::{Duration, SystemTime},
};

use chrono::{DateTime, Utc};
use statman::{scheduler::FlushScheduler, snapshot::StatsSnapshot, Stats};
// signal handling for a graceful exit
let runflag = Arc::new(AtomicBool::new(true));
{
    let runflag = Arc::clone(&runflag);
    ctrlc::set_handler(move || {
        runflag.store(false, Ordering::Relaxed);
    })
    .expect("Error setting Ctrl-C handler");
}

// create and spawn a scheduler that will print stats every 10 minutes
FlushScheduler::new(Stats::global())
    .with_register_callback(|snapshot: &StatsSnapshot| {
        println!(
            "{} - {:?}",
            DateTime::<Utc>::from(SystemTime::now()).format("%T"),
            snapshot
        )
    })
    .with_runflag(Arc::clone(&runflag))
    .spawn(Duration::from_secs(10))
    .unwrap();

// create a histogram stat that resets on every call to flush
let hist = Stats::global().histogram("myhist");
hist.set_reset_on_flush(true);

// record an ever increasing value to the histogram
let mut next_record = 0;
while runflag.load(Ordering::Relaxed) {
    hist.record(next_record);
    next_record += 1;
    thread::sleep(Duration::from_millis(10));
}

Output:

22:11:00 - StatsSnapshot { counters: {}, gauges_f64: {}, gauges_i64: {}, histograms: {"myhist": HistogramSnapshot { count: 597, percentiles: [(50.0, 298), (90.0, 537), (99.9, 596), (99.99, 596), (100.0, 596)] }}, sets: {} }
22:11:10 - StatsSnapshot { counters: {}, gauges_f64: {}, gauges_i64: {}, histograms: {"myhist": HistogramSnapshot { count: 994, percentiles: [(50.0, 1093), (90.0, 1491), (99.9, 1590), (99.99, 1590), (100.0, 1590)] }}, sets: {} }
22:11:20 - StatsSnapshot { counters: {}, gauges_f64: {}, gauges_i64: {}, histograms: {"myhist": HistogramSnapshot { count: 994, percentiles: [(50.0, 2087), (90.0, 2485), (99.9, 2585), (99.99, 2585), (100.0, 2585)] }}, sets: {} }

Re-exports

pub extern crate hdrhistogram;

Modules

scheduler

This module provides an optional utility that may be used to regularly schedule calls to Stats::flush.

snapshot

This module provides the data structures used by or generated by the crate::Stats::flush function.

stat

This module provides implementations of different trackable statistics

Structs

Stats

Manages underlying named stat instances.

Type Aliases

HdrHistogram