stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
#[cfg(feature = "histograms")]
use core::cmp;
use core::fmt;

use humansize::{BINARY, format_size};
use num_format::{Locale, ToFormattedString};

#[cfg(feature = "histograms")]
use crate::Histogram;
#[cfg(feature = "watermark")]
use crate::Peak;
use crate::{Stats, ThreadStats};

impl fmt::Display for Stats {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(
            f,
            "threads_live: {}",
            self.threads_live.to_formatted_string(&Locale::en)
        )?;
        writeln!(
            f,
            "threads_seen: {}",
            self.threads_seen.to_formatted_string(&Locale::en)
        )?;
        if self.untracked > 0 {
            writeln!(
                f,
                "untracked: {}",
                self.untracked.to_formatted_string(&Locale::en)
            )?;
        }

        writeln!(
            f,
            "\nreserved_sum: {}",
            format_size(self.reserved_sum, BINARY)
        )?;
        writeln!(
            f,
            "reserved_max: {}",
            format_size(self.reserved_max, BINARY)
        )?;

        writeln!(f, "\npeak_sum: {}", format_size(self.peak_sum, BINARY))?;
        if let Some(peak_avg) = self.peak_avg {
            writeln!(f, "peak_avg: {}", format_size(peak_avg, BINARY))?;
        }
        writeln!(f, "peak_max: {}", format_size(self.peak_max, BINARY))?;
        if let Some(utilization) = self.utilization() {
            writeln!(f, "utilization: {:.2}%", utilization * 100.0)?;
            writeln!(f, "waste: {}", format_size(self.waste(), BINARY))?;
        }

        #[cfg(feature = "watermark")]
        if self.saturated_count > 0 {
            writeln!(
                f,
                "saturated_count: {}",
                self.saturated_count.to_formatted_string(&Locale::en)
            )?;
        }

        if self.sample_count > 0 {
            writeln!(
                f,
                "\nsample_count: {}",
                self.sample_count.to_formatted_string(&Locale::en)
            )?;
            if let Some(sample_avg) = self.sample_avg {
                writeln!(f, "sample_avg: {}", format_size(sample_avg, BINARY))?;
            }
        }

        if self.near_limit_count > 0 {
            writeln!(
                f,
                "\nnear_limit_count: {}",
                self.near_limit_count.to_formatted_string(&Locale::en)
            )?;
        }
        if self.guard_trip_count > 0 {
            writeln!(
                f,
                "guard_trip_count: {}",
                self.guard_trip_count.to_formatted_string(&Locale::en)
            )?;
        }

        #[cfg(feature = "histograms")]
        if self.depth_histogram.total() > 0 {
            writeln!(f, "\ndepth_histogram:\n{}", self.depth_histogram)?;
        }

        Ok(())
    }
}

impl fmt::Display for ThreadStats {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "thread {} (slot {}): peak ", self.id, self.slot)?;

        #[cfg(feature = "watermark")]
        if self.saturated {
            f.write_str("≥ ")?;
        }

        write!(
            f,
            "{} of {}",
            format_size(self.peak, BINARY),
            format_size(self.size, BINARY)
        )?;
        if let Some(utilization) = self.utilization() {
            write!(f, " ({:.2}%)", utilization * 100.0)?;
        }

        if self.sample_count > 0 {
            write!(
                f,
                ", last {}, {} samples",
                format_size(self.depth_last, BINARY),
                self.sample_count.to_formatted_string(&Locale::en)
            )?;
        }

        Ok(())
    }
}

#[cfg(feature = "watermark")]
impl fmt::Display for Peak {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.is_saturated() {
            f.write_str("≥ ")?;
        }
        f.write_str(&format_size(self.bytes(), BINARY))
    }
}

#[cfg(feature = "histograms")]
impl fmt::Display for Histogram {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        const BAR_WIDTH: u128 = 40;

        let Some(first) = self.buckets().iter().position(|&c| c > 0) else {
            writeln!(f, "(empty)")?;
            return Ok(());
        };
        let last = self.buckets().iter().rposition(|&c| c > 0).unwrap();
        let max = *self.buckets()[first..=last].iter().max().unwrap();

        // widths scale with content: the count column tracks the largest
        // formatted count in the displayed range; the size column is the
        // tightest fixed width that fits every power-of-two label.
        let size_width = 7usize;
        let count_width = max.to_formatted_string(&Locale::en).len();

        for (k, &count) in (first..=last).zip(self.buckets()[first..=last].iter()) {
            let lo = 1usize << k;
            let lo_str = format_size(lo, BINARY);
            // bucket k covers [2^k, 2^(k+1) - 1]; the top bucket has no finite upper bound
            let range_str = match lo.checked_mul(2) {
                Some(hi) => format!(
                    "[{:>size_width$} .. {:>size_width$})",
                    lo_str,
                    format_size(hi, BINARY),
                ),
                None => format!("[{:>size_width$} .. {:>size_width$})", lo_str, "inf"),
            };
            write!(
                f,
                "{}: {:>count_width$}  ",
                range_str,
                count.to_formatted_string(&Locale::en),
            )?;
            let bar_len = if count == 0 {
                0
            } else {
                cmp::max(
                    1,
                    ((count as u128).saturating_mul(BAR_WIDTH) / max as u128) as usize,
                )
            };
            for _ in 0..bar_len {
                f.write_str("█")?;
            }
            writeln!(f)?;
        }
        Ok(())
    }
}