stoolap_jemalloc/prof/
pprof.rs

1// Copyright 2026 Stoolap Contributors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Encodes the profile as pprof's `profile.proto`, by hand to stay free
16//! of dependencies
17
18use super::StackCounts;
19use super::maps::{self, Mapping};
20use std::collections::HashMap;
21use std::fmt;
22
23/// Why a heap profile could not be dumped
24#[derive(Debug)]
25pub enum DumpError {
26    /// Profiling was never activated, so there is nothing to dump
27    NotActivated,
28    /// Writing the profile file failed
29    Io(std::io::Error),
30}
31
32impl fmt::Display for DumpError {
33    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
34        match self {
35            DumpError::NotActivated => f.write_str("heap profiling was never activated"),
36            DumpError::Io(e) => write!(f, "writing the heap profile: {e}"),
37        }
38    }
39}
40
41impl std::error::Error for DumpError {}
42
43// Wire types
44const VARINT: u64 = 0;
45const LEN: u64 = 2;
46
47fn varint(b: &mut Vec<u8>, mut v: u64) {
48    while v >= 0x80 {
49        b.push(v as u8 | 0x80);
50        v >>= 7;
51    }
52    b.push(v as u8);
53}
54
55fn tag(b: &mut Vec<u8>, field: u64, wire: u64) {
56    varint(b, field << 3 | wire);
57}
58
59fn uint(b: &mut Vec<u8>, field: u64, v: u64) {
60    if v != 0 {
61        tag(b, field, VARINT);
62        varint(b, v);
63    }
64}
65
66fn bytes(b: &mut Vec<u8>, field: u64, data: &[u8]) {
67    tag(b, field, LEN);
68    varint(b, data.len() as u64);
69    b.extend_from_slice(data);
70}
71
72fn packed(b: &mut Vec<u8>, field: u64, values: impl IntoIterator<Item = u64>) {
73    let mut tmp = Vec::new();
74    for v in values {
75        varint(&mut tmp, v);
76    }
77    bytes(b, field, &tmp);
78}
79
80#[derive(Default)]
81struct Strings {
82    ids: HashMap<String, u64>,
83    list: Vec<String>,
84}
85
86impl Strings {
87    fn id(&mut self, s: &str) -> u64 {
88        if self.list.is_empty() {
89            self.list.push(String::new());
90            self.ids.insert(String::new(), 0);
91        }
92        if let Some(&id) = self.ids.get(s) {
93            return id;
94        }
95        let id = self.list.len() as u64;
96        self.list.push(s.to_string());
97        self.ids.insert(s.to_string(), id);
98        id
99    }
100}
101
102/// `ValueType { type, unit }`
103fn value_type(strings: &mut Strings, ty: &str, unit: &str) -> Vec<u8> {
104    let mut b = Vec::new();
105    uint(&mut b, 1, strings.id(ty));
106    uint(&mut b, 2, strings.id(unit));
107    b
108}
109
110/// A source line of a location: the function's name, simplified for
111/// display and in full, its file and the line number
112struct Line {
113    name: String,
114    system_name: String,
115    file: String,
116    number: u64,
117}
118
119#[cfg(feature = "symbolize")]
120/// Rust's demangled name without generic arguments and trait
121/// qualifications, which pprof would otherwise cut into pieces:
122/// `<core::result::Result<T, E> as FnOnce<A>>::call_once` becomes
123/// `core::result::Result::call_once`
124fn simplify(name: &str) -> String {
125    enum Bracket {
126        Generic,
127        Qualified { trait_part: bool },
128    }
129    let mut out = String::with_capacity(name.len());
130    let mut stack: Vec<Bracket> = Vec::new();
131    let mut rest = name;
132    let mut prev = ' ';
133    while let Some(c) = rest.chars().next() {
134        let skipping = stack.iter().any(|b| {
135            matches!(
136                b,
137                Bracket::Generic | Bracket::Qualified { trait_part: true }
138            )
139        });
140        match c {
141            '<' => {
142                // `Vec<T>` and `f::<T>` are generic; `<impl Trait for T>` is not
143                let generic = skipping
144                    || (!rest.starts_with("<impl ")
145                        && out.ends_with(|p: char| p.is_alphanumeric() || p == '_' || p == ':'));
146                if generic && !skipping && out.ends_with("::") {
147                    out.truncate(out.len() - 2);
148                }
149                stack.push(if generic {
150                    Bracket::Generic
151                } else {
152                    Bracket::Qualified { trait_part: false }
153                });
154            }
155            // `->` inside generic arguments is not a closing bracket
156            '>' if !stack.is_empty() && prev != '-' => {
157                stack.pop();
158            }
159            _ if skipping => {}
160            ' ' if rest.starts_with(" as ")
161                && matches!(stack.last(), Some(Bracket::Qualified { .. })) =>
162            {
163                stack.pop();
164                stack.push(Bracket::Qualified { trait_part: true });
165                rest = &rest[" as".len()..];
166            }
167            _ => out.push(c),
168        }
169        rest = &rest[c.len_utf8()..];
170        prev = c;
171    }
172    out
173}
174
175/// Whether a line belongs to the allocator itself: by its source file,
176/// or by its name, for the allocator shims that live in the program.
177/// Builds with `debug = "line-tables-only"` name functions without their
178/// paths, so the name alone does not tell.
179fn is_internal(line: &Line) -> bool {
180    let own_source = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
181    std::path::Path::new(&line.file).starts_with(own_source)
182        || ["stoolap_jemalloc::", "__rustc::", "__rust_", "__rg_"]
183            .iter()
184            .any(|p| line.name.starts_with(p))
185}
186
187/// A location's lines without the allocator's own, which inlining puts at
188/// the innermost end; `None` when every line is the allocator's
189fn user_lines(addr: usize) -> Option<Vec<Line>> {
190    let mut lines = symbolize(addr);
191    let internal = lines.iter().take_while(|l| is_internal(l)).count();
192    if internal > 0 && internal == lines.len() {
193        return None;
194    }
195    lines.drain(..internal);
196    Some(lines)
197}
198
199#[cfg(feature = "symbolize")]
200fn symbolize(addr: usize) -> Vec<Line> {
201    let mut lines = Vec::new();
202    // Innermost first, as pprof wants inlined frames ordered
203    backtrace::resolve(addr as *mut core::ffi::c_void, |sym| {
204        let Some(name) = sym.name() else { return };
205        let system_name = format!("{name:#}");
206        lines.push(Line {
207            name: simplify(&system_name),
208            system_name,
209            file: sym
210                .filename()
211                .map(|f| f.display().to_string())
212                .unwrap_or_default(),
213            number: u64::from(sym.lineno().unwrap_or(0)),
214        });
215    });
216    lines
217}
218
219#[cfg(not(feature = "symbolize"))]
220fn symbolize(_addr: usize) -> Vec<Line> {
221    Vec::new()
222}
223
224pub(super) fn encode(stacks: &[StackCounts], interval: usize) -> Vec<u8> {
225    let mut strings = Strings::default();
226    strings.id("");
227    let mut out = Vec::new();
228
229    for (ty, unit) in [
230        ("alloc_objects", "count"),
231        ("alloc_space", "bytes"),
232        ("inuse_objects", "count"),
233        ("inuse_space", "bytes"),
234    ] {
235        let vt = value_type(&mut strings, ty, unit);
236        bytes(&mut out, 1, &vt);
237    }
238
239    let mut mappings = maps::mappings();
240    mappings.sort_by_key(|m| m.start);
241    let mapping_of = |addr: u64| -> u64 {
242        let i = mappings.partition_point(|m| m.start <= addr);
243        if i > 0 && addr < mappings[i - 1].limit {
244            i as u64
245        } else {
246            0
247        }
248    };
249
250    let mut symbols: HashMap<usize, Option<Vec<Line>>> = HashMap::new();
251    let mut locations = Locations::default();
252    // Whether every location in each mapping got symbols; the symbolizer
253    // misses libraries loaded after its first use, and those are left for
254    // pprof to symbolize
255    let mut symbolized = vec![cfg!(feature = "symbolize"); mappings.len() + 1];
256
257    for s in stacks {
258        if s.alloc_objects == 0 {
259            continue;
260        }
261        let mut ids = Vec::with_capacity(s.frames.len());
262        for &addr in s.frames {
263            let Some(lines) = symbols.entry(addr).or_insert_with(|| user_lines(addr)) else {
264                // The allocator's frames are only at the top of a stack
265                continue;
266            };
267            let mapping = mapping_of(addr as u64);
268            if lines.is_empty() {
269                symbolized[mapping as usize] = false;
270            }
271            ids.push(locations.id(addr, lines, mapping, &mut strings));
272        }
273        let mut sample = Vec::new();
274        packed(&mut sample, 1, ids);
275        packed(
276            &mut sample,
277            2,
278            [
279                s.alloc_objects,
280                s.alloc_bytes,
281                s.inuse_objects,
282                s.inuse_bytes,
283            ],
284        );
285        bytes(&mut out, 2, &sample);
286    }
287
288    for (i, m) in mappings.iter().enumerate() {
289        let complete = u64::from(symbolized[i + 1]);
290        out.extend(encode_mapping(&mut strings, i as u64 + 1, m, complete));
291    }
292    out.extend(locations.encoded);
293    out.extend(locations.functions_encoded);
294
295    let now = std::time::SystemTime::now()
296        .duration_since(std::time::UNIX_EPOCH)
297        .map_or(0, |d| d.as_nanos() as u64);
298    uint(&mut out, 9, now);
299    let period_type = value_type(&mut strings, "space", "bytes");
300    bytes(&mut out, 11, &period_type);
301    uint(&mut out, 12, interval as u64);
302    let default = strings.id("inuse_space");
303    uint(&mut out, 14, default);
304
305    for s in &strings.list {
306        bytes(&mut out, 6, s.as_bytes());
307    }
308    out
309}
310
311/// Locations and the functions their lines name, each encoded once
312#[derive(Default)]
313struct Locations {
314    ids: HashMap<usize, u64>,
315    /// By full name and file: simplified names of different functions,
316    /// such as two traits' methods on one type, can be the same
317    functions: HashMap<(String, String), u64>,
318    encoded: Vec<u8>,
319    functions_encoded: Vec<u8>,
320}
321
322impl Locations {
323    /// The id of the location at `addr`, encoding it on first use
324    fn id(&mut self, addr: usize, lines: &[Line], mapping: u64, strings: &mut Strings) -> u64 {
325        if let Some(&id) = self.ids.get(&addr) {
326            return id;
327        }
328        let id = self.ids.len() as u64 + 1;
329        self.ids.insert(addr, id);
330        let mut loc = Vec::new();
331        uint(&mut loc, 1, id);
332        uint(&mut loc, 2, mapping);
333        uint(&mut loc, 3, addr as u64);
334        for line in lines {
335            let mut l = Vec::new();
336            uint(&mut l, 1, self.function(line, strings));
337            uint(&mut l, 2, line.number);
338            bytes(&mut loc, 4, &l);
339        }
340        bytes(&mut self.encoded, 4, &loc);
341        id
342    }
343
344    fn function(&mut self, line: &Line, strings: &mut Strings) -> u64 {
345        let key = (line.system_name.clone(), line.file.clone());
346        if let Some(&id) = self.functions.get(&key) {
347            return id;
348        }
349        let id = self.functions.len() as u64 + 1;
350        let mut f = Vec::new();
351        uint(&mut f, 1, id);
352        uint(&mut f, 2, strings.id(&line.name));
353        uint(&mut f, 3, strings.id(&line.system_name));
354        uint(&mut f, 4, strings.id(&line.file));
355        bytes(&mut self.functions_encoded, 5, &f);
356        self.functions.insert(key, id);
357        id
358    }
359}
360
361/// A mapping; `symbolized` says whether its locations carry their
362/// functions and lines already
363fn encode_mapping(strings: &mut Strings, id: u64, m: &Mapping, symbolized: u64) -> Vec<u8> {
364    let mut b = Vec::new();
365    uint(&mut b, 1, id);
366    uint(&mut b, 2, m.start);
367    uint(&mut b, 3, m.limit);
368    uint(&mut b, 4, m.offset);
369    uint(&mut b, 5, strings.id(&m.path));
370    for field in 7..=10 {
371        uint(&mut b, field, symbolized);
372    }
373    let mut out = Vec::new();
374    bytes(&mut out, 3, &b);
375    out
376}
377
378#[cfg(all(test, feature = "symbolize"))]
379mod tests {
380    use super::{Line, is_internal, simplify};
381
382    fn line(name: &str, file: &str) -> Line {
383        Line {
384            name: name.to_string(),
385            system_name: name.to_string(),
386            file: file.to_string(),
387            number: 1,
388        }
389    }
390
391    /// With line tables only, names come without paths: the allocator's own
392    /// frames are still told by their files
393    #[test]
394    fn internal_frames_without_paths() {
395        let own = format!("{}/src/malloc.rs", env!("CARGO_MANIFEST_DIR"));
396        assert!(is_internal(&line("alloc", &own)));
397        assert!(is_internal(&line("stoolap_jemalloc::malloc::alloc", "")));
398        assert!(is_internal(&line("__rust_alloc", "/app/src/lib.rs")));
399        assert!(!is_internal(&line(
400            "alloc",
401            "/rustlib/src/rust/library/alloc/src/alloc.rs"
402        )));
403        assert!(!is_internal(&line(
404            "add_versions_batch",
405            "/app/src/storage/mvcc.rs"
406        )));
407    }
408
409    #[test]
410    fn simplifies_rust_names() {
411        let cases = [
412            ("alloc::raw_vec::finish_grow", "alloc::raw_vec::finish_grow"),
413            (
414                "<alloc::raw_vec::RawVec<T,A>>::finish_grow",
415                "alloc::raw_vec::RawVec::finish_grow",
416            ),
417            (
418                "<core::result::Result<T, E> as core::ops::function::FnOnce<A>>::call_once",
419                "core::result::Result::call_once",
420            ),
421            ("<&T as core::fmt::Display>::fmt", "&T::fmt"),
422            (
423                "std::thread::Builder::spawn::{{closure}}",
424                "std::thread::Builder::spawn::{{closure}}",
425            ),
426            ("foo::<impl Fn() -> u8>::bar", "foo::impl Fn() -> u8::bar"),
427            (
428                "RawVecInner::reserve::do_reserve_and_handle::<alloc::alloc::Global>",
429                "RawVecInner::reserve::do_reserve_and_handle",
430            ),
431            (
432                "core::ptr::drop_in_place::<alloc::vec::Vec<u8>>",
433                "core::ptr::drop_in_place",
434            ),
435        ];
436        for (name, want) in cases {
437            assert_eq!(simplify(name), want, "{name}");
438        }
439    }
440}
stoolap_jemalloc/prof/pprof.rs

stoolap_jemalloc/prof/
pprof.rs
