second-brain-api 0.10.0

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
//! Allocator residency accounting for `/v1/status`.
//!
//! The daemon runs under a hard `MemoryMax` and has twice been cgroup-OOM-
//! killed on anonymous RSS with no retained structure anywhere near the size
//! of the resident set: the store holds ~12k memories (~18 MB of embeddings)
//! while RSS sits above 1.7 GB. Anonymous RSS alone cannot say whether those
//! bytes are live data or memory the allocator has taken from the kernel and
//! not given back, and that distinction picks the remedy: freed-but-retained
//! bytes point at glibc's per-thread arenas, whose non-main arenas only ever
//! trim their top chunk, while live bytes point at a working set that simply
//! does not fit the cap.
//!
//! `mallinfo2` aggregates every arena, and glibc is where both the Rust side
//! and the C/C++ side (onnxruntime, usearch, sqlite) get their memory, so a
//! single reading covers the whole process.

use std::path::Path;

/// glibc's non-main arenas are 64 MiB mmaps aligned to their own size, so an
/// anonymous mapping matching both is an arena rather than an ordinary large
/// allocation. Counting them turns "how fragmented is this" into a number that
/// can be watched over time.
const ARENA_BYTES: u64 = 64 * 1024 * 1024;

#[derive(Debug, Clone, Copy, Default, serde::Serialize)]
pub struct HeapStats {
    /// In-use bytes: arena chunks handed out, plus live mmapped allocations.
    pub live_bytes: u64,
    /// Bytes the allocator holds free inside arenas it has not returned.
    pub free_bytes: u64,
    /// Total bytes the allocator has taken from the kernel.
    pub system_bytes: u64,
    /// Anonymous resident set, the figure the cgroup limit is enforced against.
    pub rss_anon_bytes: u64,
    /// Count of mappings carrying glibc's non-main arena signature.
    pub arena_mappings: usize,
}

impl HeapStats {
    /// Share of the allocator's footprint that is free but still charged to
    /// the process. A high value under a flat live figure is the signature of
    /// arena retention rather than of a working set that outgrew its cap.
    pub fn retained_fraction(&self) -> f64 {
        if self.system_bytes == 0 {
            return 0.0;
        }
        self.free_bytes as f64 / self.system_bytes as f64
    }
}

#[cfg(target_env = "gnu")]
fn allocator_bytes() -> (u64, u64, u64) {
    // SAFETY: mallinfo2 takes no arguments, reads only allocator state behind
    // its own locks, and returns a plain value type.
    let info = unsafe { libc::mallinfo2() };
    let arena = info.arena as u64;
    let mmapped = info.hblkhd as u64;
    let in_use = info.uordblks as u64;
    let free = info.fordblks as u64;
    (in_use + mmapped, free, arena + mmapped)
}

#[cfg(not(target_env = "gnu"))]
fn allocator_bytes() -> (u64, u64, u64) {
    (0, 0, 0)
}

pub fn rss_anon_bytes(status_path: &Path) -> u64 {
    let Ok(status) = std::fs::read_to_string(status_path) else {
        return 0;
    };
    rss_anon_from_status(&status)
}

fn rss_anon_from_status(status: &str) -> u64 {
    for line in status.lines() {
        if let Some(rest) = line.strip_prefix("RssAnon:") {
            let kb: u64 = rest
                .trim()
                .trim_end_matches("kB")
                .trim()
                .parse()
                .unwrap_or(0);
            return kb * 1024;
        }
    }
    0
}

pub fn arena_mappings(maps_path: &Path) -> usize {
    let Ok(maps) = std::fs::read_to_string(maps_path) else {
        return 0;
    };
    arena_mappings_from_maps(&maps)
}

fn arena_mappings_from_maps(maps: &str) -> usize {
    maps.lines()
        .filter(|line| {
            let mut fields = line.split_whitespace();
            let Some(range) = fields.next() else {
                return false;
            };
            // A named mapping is a file, a stack or the main heap; only
            // unnamed ones can be a non-main arena.
            if fields.clone().count() >= 5 {
                return false;
            }
            let Some((start, end)) = range.split_once('-') else {
                return false;
            };
            let (Ok(start), Ok(end)) =
                (u64::from_str_radix(start, 16), u64::from_str_radix(end, 16))
            else {
                return false;
            };
            end - start == ARENA_BYTES && start % ARENA_BYTES == 0
        })
        .count()
}

pub fn heap_stats() -> HeapStats {
    let (live_bytes, free_bytes, system_bytes) = allocator_bytes();
    HeapStats {
        live_bytes,
        free_bytes,
        system_bytes,
        rss_anon_bytes: rss_anon_bytes(Path::new("/proc/self/status")),
        arena_mappings: arena_mappings(Path::new("/proc/self/maps")),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rss_anon_is_read_as_bytes() {
        let status = "Name:\tsb\nVmRSS:\t 1653472 kB\nRssAnon:\t 1626960 kB\nThreads:\t24\n";
        assert_eq!(rss_anon_from_status(status), 1_626_960 * 1024);
    }

    #[test]
    fn rss_anon_missing_field_reads_zero() {
        assert_eq!(rss_anon_from_status("Name:\tsb\nThreads:\t24\n"), 0);
    }

    #[test]
    fn only_unnamed_64mib_aligned_mappings_count_as_arenas() {
        let maps = concat!(
            // An arena: unnamed, exactly 64 MiB, aligned to 64 MiB.
            "7f0004000000-7f0008000000 rw-p 00000000 00:00 0\n",
            // Same size and alignment but file-backed, so not an arena.
            "7f0010000000-7f0014000000 rw-p 00000000 08:01 1234 /lib/libc.so.6\n",
            // Unnamed and 64 MiB but not 64 MiB-aligned.
            "7f0018100000-7f001c100000 rw-p 00000000 00:00 0\n",
            // Unnamed and aligned but a 2 MiB thread stack.
            "7f0020000000-7f0020200000 rw-p 00000000 00:00 0\n",
            "555500000000-555500100000 rw-p 00000000 00:00 0 [heap]\n",
        );
        assert_eq!(arena_mappings_from_maps(maps), 1);
    }

    #[test]
    fn retained_fraction_is_free_over_system_and_zero_when_empty() {
        let stats = HeapStats {
            free_bytes: 300,
            system_bytes: 1200,
            ..Default::default()
        };
        assert!((stats.retained_fraction() - 0.25).abs() < 1e-9);
        assert_eq!(HeapStats::default().retained_fraction(), 0.0);
    }
}