heaptrack

heaptrack

用途

指导 Agent 使用 heaptrack 在 Linux 上进行堆内存分配分析：记录分配跟踪信息，使用 heaptrack_print 进行分析，识别内存泄漏和热点，并比较不同运行结果。

触发条件

• “如何找到我的 C++ 程序中的内存分配热点？”
• “我的程序占用内存太多了——如何找到问题所在？”
• “如何使用 heaptrack 检测内存泄漏？”
• “heaptrack 是什么？它与 Valgrind massif 有何不同？”
• “如何比较两个程序版本的内存使用情况？”
• “如何解读 heaptrack_print 输出？”

工作流

1. 安装

# Ubuntu/Debian
sudo apt-get install heaptrack heaptrack-gui

# Fedora
sudo dnf install heaptrack

# Arch
sudo pacman -S heaptrack

# Build from source
git clone https://github.com/KDE/heaptrack.git
cmake -S heaptrack -B heaptrack-build -DCMAKE_BUILD_TYPE=Release
cmake --build heaptrack-build -j$(nproc)

2. 基本用法

# Profile a program (generates heaptrack.<prog>.<pid>.zst)
heaptrack ./myapp arg1 arg2

# Attach to running process
heaptrack --pid 12345

# Analyse the trace file
heaptrack_print heaptrack.myapp.12345.zst

# GUI analysis (if heaptrack-gui installed)
heaptrack_gui heaptrack.myapp.12345.zst

3. 为更好的分析效果进行构建

# Build with debug symbols (essential for readable backtraces)
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build

# Then profile
heaptrack ./build/myapp

4. 解读 heaptrack_print 输出

heaptrack_print heaptrack.myapp.*.zst 2>/dev/null

主要部分：

total runtime: 2.34s
calls to allocation functions: 145,234 (62,064/s)
temporary allocations: 89,123 (38,087/s)
peak heap memory consumption: 45.23MB
peak RSS (including heap): 78.45MB
total memory leaked: 2.34MB

# Top allocation hotspots (by peak memory)
hotspot 1: 12.34MB peak
  myapp::cache::Cache::insert(...)
    at src/cache.cpp:142
  ...

# Top leaked allocations
leak 1: 2.34MB leaked in 1,234 allocations
  myapp::connection::Connection::new(...)
    at src/connection.cpp:67

指标	含义
total memory leaked	已分配但从未释放的内存
peak heap consumption	任意时刻的最大堆内存占用
temporary allocations	在一次调用栈内分配并释放的内存
calls to allocation functions	malloc/new/realloc 的总调用次数

5. 筛选和分析选项

# Show top N hotspots
heaptrack_print -p 10 heaptrack.myapp.*.zst  # top 10 hotspots

# Show flamegraph data
heaptrack_print -f heaptrack.myapp.*.zst > alloc.folded
flamegraph.pl alloc.folded > alloc.svg

# Show only leaked allocations
heaptrack_print -l heaptrack.myapp.*.zst

# Show allocations above threshold
heaptrack_print --min-cost 1048576 heaptrack.myapp.*.zst  # >1MB only

# Short summary
heaptrack_print -s heaptrack.myapp.*.zst

6. 比较两次运行

# Record baseline
heaptrack ./myapp --config baseline.conf
mv heaptrack.myapp.*.zst before.zst

# Make changes, record again
heaptrack ./myapp --config new.conf
mv heaptrack.myapp.*.zst after.zst

# Compare (shows diff of hotspots)
heaptrack_print before.zst | head -20 > before.txt
heaptrack_print after.zst  | head -20 > after.txt
diff before.txt after.txt

7. heaptrack 与 Valgrind massif 对比

特性	heaptrack	Valgrind massif
开销	~2-3x	~20x
输出	压缩跟踪信息 + GUI	文本/ms_print
泄漏检测	是	是
峰值跟踪	是	是
时间视图	是（GUI）	是（ms_print）
平台	仅 Linux	Linux、macOS
是否需要重新编译	否	否
调用图	完整堆栈跟踪	完整堆栈跟踪

大多数情况下使用 heaptrack；需要跨平台或详细比较快照时使用 massif。

8. 与 Rust 集成

使用系统分配器时，heaptrack 可用于 Rust 二进制文件：

// Rust: use system allocator so heaptrack can intercept
use std::alloc::System;
#[global_allocator]
static A: System = System;

# Profile Rust binary
cargo build --release
heaptrack ./target/release/myapp

# Note: debug symbols improve backtraces
cargo build --profile release-with-debug
heaptrack ./target/release-with-debug/myapp

有关 heaptrack_print 输出参考和 GUI 用法，请参阅 references/heaptrack-analysis.md。

相关技能

• 使用 skills/profilers/valgrind 进行 Memcheck（正确性检查）和 massif（替代堆分析器）
• 使用 skills/profilers/linux-perf 配合内存分析进行 CPU 分析
• 使用 skills/rust/rust-profiling 了解 Rust 专用的分配分析方法
• 使用 skills/runtimes/sanitizers — 通过 ASan LeakSanitizer 检测泄漏，且无需承担分析开销