Skip to main content

second_brain_api/
heap.rs

1//! Allocator residency accounting for `/v1/status`.
2//!
3//! The daemon runs under a hard `MemoryMax` and has twice been cgroup-OOM-
4//! killed on anonymous RSS with no retained structure anywhere near the size
5//! of the resident set: the store holds ~12k memories (~18 MB of embeddings)
6//! while RSS sits above 1.7 GB. Anonymous RSS alone cannot say whether those
7//! bytes are live data or memory the allocator has taken from the kernel and
8//! not given back, and that distinction picks the remedy: freed-but-retained
9//! bytes point at glibc's per-thread arenas, whose non-main arenas only ever
10//! trim their top chunk, while live bytes point at a working set that simply
11//! does not fit the cap.
12//!
13//! `mallinfo2` aggregates every arena, and glibc is where both the Rust side
14//! and the C/C++ libraries that use malloc (onnxruntime, sqlite) get their
15//! memory; usearch maps its own tapes, which the component report counts.
16
17use std::path::Path;
18use std::sync::{Mutex, PoisonError};
19
20use second_brain_core::residency::{self, ComponentResidency, IndexMemory};
21
22use crate::AppState;
23
24/// glibc's non-main arenas are 64 MiB mmaps aligned to their own size, so an
25/// anonymous mapping matching both is an arena rather than an ordinary large
26/// allocation. Counting them turns "how fragmented is this" into a number that
27/// can be watched over time.
28const ARENA_BYTES: u64 = 64 * 1024 * 1024;
29
30#[derive(Debug, Clone, Copy, Default, serde::Serialize)]
31pub struct HeapStats {
32    /// In-use bytes: arena chunks handed out, plus live mmapped allocations.
33    pub live_bytes: u64,
34    /// Bytes the allocator holds free inside arenas, resident or not; the
35    /// `allocator_free` component counts only the resident part.
36    pub free_bytes: u64,
37    /// Total bytes the allocator has taken from the kernel.
38    pub system_bytes: u64,
39    /// Anonymous resident set, the figure the cgroup limit is enforced against.
40    pub rss_anon_bytes: u64,
41    /// Count of mappings carrying glibc's non-main arena signature.
42    pub arena_mappings: usize,
43}
44
45/// `HeapStats` plus where the anonymous resident set goes, per component.
46#[derive(Debug, Clone, Copy, serde::Serialize)]
47pub struct HeapReport {
48    #[serde(flatten)]
49    pub stats: HeapStats,
50    pub components: ComponentResidency,
51    /// `rss_anon_bytes` minus the components' total; negative when a
52    /// component counts bytes that are not resident.
53    pub unattributed_bytes: i64,
54}
55
56static INDEX_WRITER: Mutex<Option<IndexMemory>> = Mutex::new(None);
57
58/// What the drain loop's writer `Indexes` holds, or `None` while it is
59/// released. Process-wide, like the RSS it is compared against.
60pub fn record_index_writer(memory: Option<IndexMemory>) {
61    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner) = memory;
62}
63
64fn recorded_index_writer() -> Option<IndexMemory> {
65    *INDEX_WRITER.lock().unwrap_or_else(PoisonError::into_inner)
66}
67
68pub fn component_residency(state: &AppState) -> ComponentResidency {
69    let reader = state.indexes.as_ref().map(|indexes| {
70        indexes
71            .read()
72            .unwrap_or_else(PoisonError::into_inner)
73            .memory()
74    });
75    residency::measure(
76        state.embedder.as_deref(),
77        state.reranker.as_deref(),
78        reader,
79        recorded_index_writer(),
80    )
81}
82
83/// Takes the reader index lock briefly, so call it off the async runtime.
84pub fn heap_report(state: &AppState) -> HeapReport {
85    let stats = heap_stats();
86    let components = component_residency(state);
87    HeapReport {
88        stats,
89        components,
90        unattributed_bytes: stats.rss_anon_bytes as i64 - components.total() as i64,
91    }
92}
93
94pub fn arena_mappings(maps_path: &Path) -> usize {
95    let Ok(maps) = std::fs::read_to_string(maps_path) else {
96        return 0;
97    };
98    arena_mappings_from_maps(&maps)
99}
100
101fn arena_mappings_from_maps(maps: &str) -> usize {
102    maps.lines()
103        .filter(|line| {
104            let mut fields = line.split_whitespace();
105            let Some(range) = fields.next() else {
106                return false;
107            };
108            // A named mapping is a file, a stack or the main heap; only
109            // unnamed ones can be a non-main arena.
110            if fields.clone().count() >= 5 {
111                return false;
112            }
113            let Some((start, end)) = range.split_once('-') else {
114                return false;
115            };
116            let (Ok(start), Ok(end)) =
117                (u64::from_str_radix(start, 16), u64::from_str_radix(end, 16))
118            else {
119                return false;
120            };
121            end - start == ARENA_BYTES && start % ARENA_BYTES == 0
122        })
123        .count()
124}
125
126pub fn heap_stats() -> HeapStats {
127    let allocator = residency::allocator_bytes();
128    HeapStats {
129        live_bytes: allocator.live,
130        free_bytes: allocator.free,
131        system_bytes: allocator.system,
132        rss_anon_bytes: residency::rss_anon_bytes(),
133        arena_mappings: arena_mappings(Path::new("/proc/self/maps")),
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140
141    #[test]
142    fn only_unnamed_64mib_aligned_mappings_count_as_arenas() {
143        let maps = concat!(
144            // An arena: unnamed, exactly 64 MiB, aligned to 64 MiB.
145            "7f0004000000-7f0008000000 rw-p 00000000 00:00 0\n",
146            // Same size and alignment but file-backed, so not an arena.
147            "7f0010000000-7f0014000000 rw-p 00000000 08:01 1234 /lib/libc.so.6\n",
148            // Unnamed and 64 MiB but not 64 MiB-aligned.
149            "7f0018100000-7f001c100000 rw-p 00000000 00:00 0\n",
150            // Unnamed and aligned but a 2 MiB thread stack.
151            "7f0020000000-7f0020200000 rw-p 00000000 00:00 0\n",
152            "555500000000-555500100000 rw-p 00000000 00:00 0 [heap]\n",
153        );
154        assert_eq!(arena_mappings_from_maps(maps), 1);
155    }
156}