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
176fn is_internal(line: &Line) -> bool {
177    ["stoolap_jemalloc::", "__rustc::", "__rust_", "__rg_"]
178        .iter()
179        .any(|p| line.name.starts_with(p))
180}
181
182/// A location's lines without the allocator's own, which inlining puts at
183/// the innermost end; `None` when every line is the allocator's
184fn user_lines(addr: usize) -> Option<Vec<Line>> {
185    let mut lines = symbolize(addr);
186    let internal = lines.iter().take_while(|l| is_internal(l)).count();
187    if internal > 0 && internal == lines.len() {
188        return None;
189    }
190    lines.drain(..internal);
191    Some(lines)
192}
193
194#[cfg(feature = "symbolize")]
195fn symbolize(addr: usize) -> Vec<Line> {
196    let mut lines = Vec::new();
197    // Innermost first, as pprof wants inlined frames ordered
198    backtrace::resolve(addr as *mut core::ffi::c_void, |sym| {
199        let Some(name) = sym.name() else { return };
200        let system_name = format!("{name:#}");
201        lines.push(Line {
202            name: simplify(&system_name),
203            system_name,
204            file: sym
205                .filename()
206                .map(|f| f.display().to_string())
207                .unwrap_or_default(),
208            number: u64::from(sym.lineno().unwrap_or(0)),
209        });
210    });
211    lines
212}
213
214#[cfg(not(feature = "symbolize"))]
215fn symbolize(_addr: usize) -> Vec<Line> {
216    Vec::new()
217}
218
219pub(super) fn encode(stacks: &[StackCounts], interval: usize) -> Vec<u8> {
220    let mut strings = Strings::default();
221    strings.id("");
222    let mut out = Vec::new();
223
224    for (ty, unit) in [
225        ("alloc_objects", "count"),
226        ("alloc_space", "bytes"),
227        ("inuse_objects", "count"),
228        ("inuse_space", "bytes"),
229    ] {
230        let vt = value_type(&mut strings, ty, unit);
231        bytes(&mut out, 1, &vt);
232    }
233
234    let mut mappings = maps::mappings();
235    mappings.sort_by_key(|m| m.start);
236    let mapping_of = |addr: u64| -> u64 {
237        let i = mappings.partition_point(|m| m.start <= addr);
238        if i > 0 && addr < mappings[i - 1].limit {
239            i as u64
240        } else {
241            0
242        }
243    };
244
245    let mut symbols: HashMap<usize, Option<Vec<Line>>> = HashMap::new();
246    let mut locations = Locations::default();
247    // Whether every location in each mapping got symbols; the symbolizer
248    // misses libraries loaded after its first use, and those are left for
249    // pprof to symbolize
250    let mut symbolized = vec![cfg!(feature = "symbolize"); mappings.len() + 1];
251
252    for s in stacks {
253        if s.alloc_objects == 0 {
254            continue;
255        }
256        let mut ids = Vec::with_capacity(s.frames.len());
257        for &addr in s.frames {
258            let Some(lines) = symbols.entry(addr).or_insert_with(|| user_lines(addr)) else {
259                // The allocator's frames are only at the top of a stack
260                continue;
261            };
262            let mapping = mapping_of(addr as u64);
263            if lines.is_empty() {
264                symbolized[mapping as usize] = false;
265            }
266            ids.push(locations.id(addr, lines, mapping, &mut strings));
267        }
268        let mut sample = Vec::new();
269        packed(&mut sample, 1, ids);
270        packed(
271            &mut sample,
272            2,
273            [
274                s.alloc_objects,
275                s.alloc_bytes,
276                s.inuse_objects,
277                s.inuse_bytes,
278            ],
279        );
280        bytes(&mut out, 2, &sample);
281    }
282
283    for (i, m) in mappings.iter().enumerate() {
284        let complete = u64::from(symbolized[i + 1]);
285        out.extend(encode_mapping(&mut strings, i as u64 + 1, m, complete));
286    }
287    out.extend(locations.encoded);
288    out.extend(locations.functions_encoded);
289
290    let now = std::time::SystemTime::now()
291        .duration_since(std::time::UNIX_EPOCH)
292        .map_or(0, |d| d.as_nanos() as u64);
293    uint(&mut out, 9, now);
294    let period_type = value_type(&mut strings, "space", "bytes");
295    bytes(&mut out, 11, &period_type);
296    uint(&mut out, 12, interval as u64);
297    let default = strings.id("inuse_space");
298    uint(&mut out, 14, default);
299
300    for s in &strings.list {
301        bytes(&mut out, 6, s.as_bytes());
302    }
303    out
304}
305
306/// Locations and the functions their lines name, each encoded once
307#[derive(Default)]
308struct Locations {
309    ids: HashMap<usize, u64>,
310    /// By full name and file: simplified names of different functions,
311    /// such as two traits' methods on one type, can be the same
312    functions: HashMap<(String, String), u64>,
313    encoded: Vec<u8>,
314    functions_encoded: Vec<u8>,
315}
316
317impl Locations {
318    /// The id of the location at `addr`, encoding it on first use
319    fn id(&mut self, addr: usize, lines: &[Line], mapping: u64, strings: &mut Strings) -> u64 {
320        if let Some(&id) = self.ids.get(&addr) {
321            return id;
322        }
323        let id = self.ids.len() as u64 + 1;
324        self.ids.insert(addr, id);
325        let mut loc = Vec::new();
326        uint(&mut loc, 1, id);
327        uint(&mut loc, 2, mapping);
328        uint(&mut loc, 3, addr as u64);
329        for line in lines {
330            let mut l = Vec::new();
331            uint(&mut l, 1, self.function(line, strings));
332            uint(&mut l, 2, line.number);
333            bytes(&mut loc, 4, &l);
334        }
335        bytes(&mut self.encoded, 4, &loc);
336        id
337    }
338
339    fn function(&mut self, line: &Line, strings: &mut Strings) -> u64 {
340        let key = (line.system_name.clone(), line.file.clone());
341        if let Some(&id) = self.functions.get(&key) {
342            return id;
343        }
344        let id = self.functions.len() as u64 + 1;
345        let mut f = Vec::new();
346        uint(&mut f, 1, id);
347        uint(&mut f, 2, strings.id(&line.name));
348        uint(&mut f, 3, strings.id(&line.system_name));
349        uint(&mut f, 4, strings.id(&line.file));
350        bytes(&mut self.functions_encoded, 5, &f);
351        self.functions.insert(key, id);
352        id
353    }
354}
355
356/// A mapping; `symbolized` says whether its locations carry their
357/// functions and lines already
358fn encode_mapping(strings: &mut Strings, id: u64, m: &Mapping, symbolized: u64) -> Vec<u8> {
359    let mut b = Vec::new();
360    uint(&mut b, 1, id);
361    uint(&mut b, 2, m.start);
362    uint(&mut b, 3, m.limit);
363    uint(&mut b, 4, m.offset);
364    uint(&mut b, 5, strings.id(&m.path));
365    for field in 7..=10 {
366        uint(&mut b, field, symbolized);
367    }
368    let mut out = Vec::new();
369    bytes(&mut out, 3, &b);
370    out
371}
372
373#[cfg(all(test, feature = "symbolize"))]
374mod tests {
375    use super::simplify;
376
377    #[test]
378    fn simplifies_rust_names() {
379        let cases = [
380            ("alloc::raw_vec::finish_grow", "alloc::raw_vec::finish_grow"),
381            (
382                "<alloc::raw_vec::RawVec<T,A>>::finish_grow",
383                "alloc::raw_vec::RawVec::finish_grow",
384            ),
385            (
386                "<core::result::Result<T, E> as core::ops::function::FnOnce<A>>::call_once",
387                "core::result::Result::call_once",
388            ),
389            ("<&T as core::fmt::Display>::fmt", "&T::fmt"),
390            (
391                "std::thread::Builder::spawn::{{closure}}",
392                "std::thread::Builder::spawn::{{closure}}",
393            ),
394            ("foo::<impl Fn() -> u8>::bar", "foo::impl Fn() -> u8::bar"),
395            (
396                "RawVecInner::reserve::do_reserve_and_handle::<alloc::alloc::Global>",
397                "RawVecInner::reserve::do_reserve_and_handle",
398            ),
399            (
400                "core::ptr::drop_in_place::<alloc::vec::Vec<u8>>",
401                "core::ptr::drop_in_place",
402            ),
403        ];
404        for (name, want) in cases {
405            assert_eq!(simplify(name), want, "{name}");
406        }
407    }
408}
stoolap_jemalloc/prof/pprof.rs

stoolap_jemalloc/prof/
pprof.rs
