stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
use core::{cmp, ops::Sub};

#[cfg(feature = "histograms")]
use crate::Histogram;
use crate::registry;

/// Everything known about a single tracked thread.
///
/// Snapshots of individual threads are what [`crate::Stats`] is aggregated from;
/// they are worth looking at directly when the aggregate says something is deep
/// and the next question is *which thread*.
///
/// There is more to learn about a thread than this, and later versions will learn
/// it, so the struct is `#[non_exhaustive]`: read the fields you want rather than
/// destructuring all of them.
#[derive(Debug, Default, Clone, Copy)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
#[non_exhaustive]
pub struct ThreadStats {
    /// The registry slot the thread occupies. Stable for the thread's lifetime,
    /// and reused afterwards.
    pub slot: usize,
    /// The thread's identifier as the platform knows it: the kernel thread id on
    /// Linux, the `pthread_t` handle on other unices, the thread id on Windows,
    /// and `0` where none is available.
    pub id: u64,
    /// The address one past the highest byte of the thread's stack.
    pub base: usize,
    /// The lowest usable address of the thread's stack.
    pub limit: usize,
    /// The size of the thread's stack in bytes; this is what the thread reserves,
    /// as opposed to what it uses.
    pub size: usize,
    /// The depth recorded by the most recent [`crate::sample`] call, which may be
    /// arbitrarily stale — a thread that never samples never updates it.
    pub depth_last: usize,
    /// The deepest stack use known for this thread, from sampling and watermark
    /// scans alike.
    pub peak: usize,
    /// Whether [`peak`](ThreadStats::peak) is a lower bound because the thread
    /// consumed its entire painted region.
    #[cfg(feature = "watermark")]
    pub saturated: bool,
    /// The number of depth observations recorded for this thread.
    pub sample_count: u64,
    /// The sum of the depths observed for this thread.
    pub sample_sum: u64,
    /// The number of observations that found less headroom than the configured
    /// reserve.
    pub near_limit_count: u64,
    /// The number of times [`crate::has_headroom`] denied this thread.
    pub guard_trip_count: u64,
}

impl ThreadStats {
    /// Returns the stack the thread runs on.
    pub const fn stack(&self) -> Option<crate::Stack> {
        crate::Stack::from_bounds(self.limit, self.base)
    }

    /// Returns the share of the thread's stack that its peak accounts for, as a
    /// fraction between 0 and 1.
    pub fn utilization(&self) -> Option<f64> {
        if self.size == 0 {
            return None;
        }
        Some(self.peak as f64 / self.size as f64)
    }
}

/// A summary of the stack use of a whole process.
///
/// # Field relationships
///
/// The fields fall into two kinds, and they behave differently under
/// subtraction — which is what [`crate::measure`] does:
///
/// - **counters** ([`Stats::threads_seen`], [`Stats::sample_count`],
///   [`Stats::sample_sum`], [`Stats::near_limit_count`],
///   [`Stats::guard_trip_count`], [`Stats::untracked`] and the histogram) only
///   ever grow, so a difference between two snapshots is the activity in
///   between.
///
/// - **gauges** ([`Stats::threads_live`], [`Stats::reserved_sum`],
///   [`Stats::reserved_max`], [`Stats::peak_sum`]
#[cfg_attr(feature = "watermark", doc = "   , [`Stats::saturated_count`])")]
#[cfg_attr(not(feature = "watermark"), doc = "   )")]
///   describe the present, so a difference is meaningless and they are carried
///   over from the newer snapshot unchanged.
///
/// [`Stats::peak_max`] is the exception on purpose: it is monotonic, and
/// subtracting it answers "how much deeper did anything get during this
/// window", which is usually the interesting question.
///
/// Note: snapshots are not atomic across fields, or even across threads; a
/// thread that starts or exits while one is being taken is described by whichever
/// side of the transition the walk happened to see.
///
/// The struct is `#[non_exhaustive]`, so that a later version can report something
/// new without that being a breaking change. Snapshots are produced by
/// [`stats()`](crate::stats) and meant to be read, so this costs nothing in
/// practice — but it does mean reading the fields you want rather than
/// destructuring all of them.
#[derive(Debug, Default, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
#[non_exhaustive]
pub struct Stats {
    /// The number of threads currently tracked.
    pub threads_live: u64,
    /// The number of threads tracked over the process' lifetime.
    pub threads_seen: u64,
    /// The number of threads that could not be tracked, either because their
    /// stack bounds were unavailable or because all [`registry::MAX_THREADS`]
    /// slots were taken.
    pub untracked: u64,
    /// The total stack space reserved by live threads. This is address space
    /// rather than memory in use — the gap between it and [`Stats::peak_sum`] is
    /// what a thread pool is paying for stacks nobody descends into.
    pub reserved_sum: u64,
    /// The largest stack reserved by a live thread.
    pub reserved_max: usize,
    /// The sum of the peak depths of live threads.
    pub peak_sum: u64,
    /// The average peak depth of live threads.
    pub peak_avg: Option<usize>,
    /// The deepest stack use ever recorded for any thread, live or exited.
    pub peak_max: usize,
    /// The number of depth observations recorded.
    pub sample_count: u64,
    /// The sum of all observed depths.
    pub sample_sum: u64,
    /// The average observed depth.
    pub sample_avg: Option<usize>,
    /// The distribution of observed depths, summed over the threads that reported
    /// them — including those that have since exited.
    #[cfg(feature = "histograms")]
    pub depth_histogram: Histogram,
    /// The number of live threads whose peak is only a lower bound, plus the
    /// number of exited threads that were in that state when they finished.
    /// Anything above zero means the painted region is too small to describe the
    /// process — see [`crate::Stackler::paint_depth`].
    #[cfg(feature = "watermark")]
    pub saturated_count: u64,
    /// The number of observations that found less headroom than the configured
    /// reserve.
    pub near_limit_count: u64,
    /// The number of times [`crate::has_headroom`] denied a caller.
    pub guard_trip_count: u64,
}

impl Stats {
    /// Returns the amount of reserved stack space that no live thread has ever
    /// descended into.
    pub const fn waste(&self) -> u64 {
        self.reserved_sum.saturating_sub(self.peak_sum)
    }

    /// Returns the share of reserved stack space that live threads have actually
    /// used, as a fraction between 0 and 1.
    ///
    /// Returns `None` if nothing is reserved, which is also the answer when no
    /// thread is tracked.
    pub fn utilization(&self) -> Option<f64> {
        if self.reserved_sum == 0 {
            return None;
        }
        Some(self.peak_sum as f64 / self.reserved_sum as f64)
    }
}

/// Returns a summary of the stack use of the whole process.
///
/// The aggregates are computed here rather than maintained as the process runs,
/// so that the measurement paths only ever write to memory owned by the thread
/// doing the measuring. The cost is one pass over the registry.
///
/// Only threads that have been seen are described, and asking for a report is not
/// being seen: a program whose only call is this one gets zeros back. One
/// [`Stackler::install`](crate::Stackler::install) — or any measurement at all, or
/// the `hook_pthread` feature — is what puts threads in the registry.
pub fn stats() -> Stats {
    let mut threads_live = 0u64;
    let mut reserved_sum = 0u64;
    let mut reserved_max = 0usize;
    let mut peak_sum = 0u64;
    let mut peak_max = 0usize;
    let mut sample_count = 0u64;
    let mut sample_sum = 0u64;
    let mut near_limit_count = 0u64;
    let mut guard_trip_count = 0u64;
    #[cfg(feature = "watermark")]
    let mut saturated_count = 0u64;

    registry::for_each_thread(|thread| {
        threads_live += 1;
        reserved_sum += thread.size as u64;
        reserved_max = cmp::max(reserved_max, thread.size);
        peak_sum += thread.peak as u64;
        peak_max = cmp::max(peak_max, thread.peak);
        sample_count += thread.sample_count;
        sample_sum += thread.sample_sum;
        near_limit_count += thread.near_limit_count;
        guard_trip_count += thread.guard_trip_count;
        #[cfg(feature = "watermark")]
        if thread.saturated {
            saturated_count += 1;
        }
    });

    // Threads that have exited keep contributing to the lifetime totals.
    let retired = registry::retired_totals();
    peak_max = cmp::max(peak_max, retired.peak_max);
    sample_count += retired.sample_count;
    sample_sum += retired.sample_sum;
    near_limit_count += retired.near_limit_count;
    guard_trip_count += retired.guard_trip_count;
    #[cfg(feature = "watermark")]
    {
        saturated_count += retired.saturated;
    }

    Stats {
        threads_live,
        threads_seen: registry::threads_seen(),
        untracked: registry::untracked(),
        reserved_sum,
        reserved_max,
        peak_sum,
        peak_avg: peak_sum.checked_div(threads_live).map(|avg| avg as usize),
        peak_max,
        sample_count,
        sample_sum,
        sample_avg: sample_sum.checked_div(sample_count).map(|avg| avg as usize),
        #[cfg(feature = "histograms")]
        depth_histogram: registry::depth_histogram(),
        #[cfg(feature = "watermark")]
        saturated_count,
        near_limit_count,
        guard_trip_count,
    }
}

impl Sub<&Stats> for &Stats {
    type Output = Stats;

    fn sub(self, old: &Stats) -> Stats {
        let sample_count = self.sample_count.saturating_sub(old.sample_count);
        let sample_sum = self.sample_sum.saturating_sub(old.sample_sum);

        Stats {
            // Gauges: the present is the present, no matter what it was before.
            threads_live: self.threads_live,
            reserved_sum: self.reserved_sum,
            reserved_max: self.reserved_max,
            peak_sum: self.peak_sum,
            peak_avg: self.peak_avg,
            #[cfg(feature = "watermark")]
            saturated_count: self.saturated_count,

            // Counters.
            threads_seen: self.threads_seen.saturating_sub(old.threads_seen),
            untracked: self.untracked.saturating_sub(old.untracked),
            peak_max: self.peak_max.saturating_sub(old.peak_max),
            sample_count,
            sample_sum,
            sample_avg: sample_sum.checked_div(sample_count).map(|avg| avg as usize),
            #[cfg(feature = "histograms")]
            depth_histogram: self.depth_histogram - old.depth_histogram,
            near_limit_count: self.near_limit_count.saturating_sub(old.near_limit_count),
            guard_trip_count: self.guard_trip_count.saturating_sub(old.guard_trip_count),
        }
    }
}

impl Sub<Stats> for Stats {
    type Output = Stats;

    fn sub(self, old: Stats) -> Stats {
        &self - &old
    }
}

impl Sub<&Stats> for Stats {
    type Output = Stats;

    fn sub(self, old: &Stats) -> Stats {
        &self - old
    }
}

impl Sub<Stats> for &Stats {
    type Output = Stats;

    fn sub(self, old: Stats) -> Stats {
        self - &old
    }
}