Back to Details

heaptrack

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

heaptrack

heaptrack

Purpose

用途

Guide agents through heaptrack for heap allocation profiling on Linux: recording allocation traces, analysing with heaptrack_print, identifying leaks and hotspots, and comparing runs.
指导Agent使用heaptrack在Linux上进行堆内存分配分析：包括记录分配轨迹、使用heaptrack_print分析数据、识别泄漏与热点，以及对比不同运行实例。

Triggers

触发场景

  • "How do I find memory allocation hotspots in my C++ program?"
  • "My program uses too much memory — how do I find where?"
  • "How do I use heaptrack to detect memory leaks?"
  • "What is heaptrack and how does it differ from Valgrind massif?"
  • "How do I compare memory usage between two program versions?"
  • "heaptrack_print output — how do I interpret it?"
  • "如何在我的C++程序中查找内存分配热点？"
  • "我的程序内存占用过高——如何定位问题？"
  • "如何使用heaptrack检测内存泄漏？"
  • "什么是heaptrack，它与Valgrind massif有何区别？"
  • "如何对比两个程序版本的内存使用情况？"
  • "heaptrack_print的输出——如何解读？"

Workflow

工作流程

1. Installation

1. 安装

bash
undefined
bash
undefined

Ubuntu/Debian

Ubuntu/Debian

sudo apt-get install heaptrack heaptrack-gui
sudo apt-get install heaptrack heaptrack-gui

Fedora

Fedora

sudo dnf install heaptrack
sudo dnf install heaptrack

Arch

Arch

sudo pacman -S heaptrack
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)
undefined
git clone https://github.com/KDE/heaptrack.git cmake -S heaptrack -B heaptrack-build -DCMAKE_BUILD_TYPE=Release cmake --build heaptrack-build -j$(nproc)
undefined

2. Basic usage

2. 基础使用

bash
undefined
bash
undefined

Profile a program (generates heaptrack.<prog>.<pid>.zst)

分析程序（生成heaptrack.<prog>.<pid>.zst文件）

heaptrack ./myapp arg1 arg2
heaptrack ./myapp arg1 arg2

Attach to running process

附加到运行中的进程

heaptrack --pid 12345
heaptrack --pid 12345

Analyse the trace file

分析轨迹文件

heaptrack_print heaptrack.myapp.12345.zst
heaptrack_print heaptrack.myapp.12345.zst

GUI analysis (if heaptrack-gui installed)

GUI分析（需安装heaptrack-gui）

heaptrack_gui heaptrack.myapp.12345.zst
undefined
heaptrack_gui heaptrack.myapp.12345.zst
undefined

3. Build for better profiling

3. 编译以优化分析效果

bash
undefined
bash
undefined

Build with debug symbols (essential for readable backtraces)

带调试符号编译（获取可读回溯信息的关键）

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build

Then profile

然后进行分析

heaptrack ./build/myapp
undefined
heaptrack ./build/myapp
undefined

4. Interpreting heaptrack_print output

4. 解读heaptrack_print输出

bash
heaptrack_print heaptrack.myapp.*.zst 2>/dev/null
Key sections:
text
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
bash
heaptrack_print heaptrack.myapp.*.zst 2>/dev/null
关键部分：
text
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)

Top allocation hotspots (by peak memory)

hotspot 1: 12.34MB peak myapp::cache::Cache::insert(...) at src/cache.cpp:142 ...
hotspot 1: 12.34MB peak myapp::cache::Cache::insert(...) at src/cache.cpp:142 ...

Top leaked allocations

Top leaked allocations

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

| Metric | Meaning |
|--------|---------|
| `total memory leaked` | Memory allocated but never freed |
| `peak heap consumption` | Maximum live heap at any point |
| `temporary allocations` | Allocated and freed within one call stack |
| `calls to allocation functions` | Total malloc/new/realloc calls |
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. Filtering and analysis options

5. 过滤与分析选项

bash
undefined
bash
undefined

Show top N hotspots

显示前N个热点

heaptrack_print -p 10 heaptrack.myapp.*.zst # top 10 hotspots
heaptrack_print -p 10 heaptrack.myapp.*.zst # 前10个热点

Show flamegraph data

生成火焰图数据

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

Show only leaked allocations

仅显示泄漏的分配

heaptrack_print -l heaptrack.myapp.*.zst
heaptrack_print -l heaptrack.myapp.*.zst

Show allocations above threshold

显示超过阈值的分配

heaptrack_print --min-cost 1048576 heaptrack.myapp.*.zst # >1MB only
heaptrack_print --min-cost 1048576 heaptrack.myapp.*.zst # 仅显示大于1MB的分配

Short summary

简短摘要

heaptrack_print -s heaptrack.myapp.*.zst
undefined
heaptrack_print -s heaptrack.myapp.*.zst
undefined

6. Comparing two runs

6. 对比两次运行结果

bash
undefined
bash
undefined

Record baseline

记录基准数据

heaptrack ./myapp --config baseline.conf mv heaptrack.myapp.*.zst before.zst
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
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
undefined
heaptrack_print before.zst | head -20 > before.txt heaptrack_print after.zst | head -20 > after.txt diff before.txt after.txt
undefined

7. heaptrack vs Valgrind massif

7. heaptrack与Valgrind massif对比

FeatureheaptrackValgrind massif
Overhead~2-3x~20x
OutputCompressed trace + GUIText/ms_print
Leak detectionYesYes
Peak trackingYesYes
Temporal viewYes (GUI)Yes (ms_print)
PlatformLinux onlyLinux, macOS
Needs recompileNoNo
Call graphFull stack tracesFull stack traces
Use heaptrack for most cases; use massif when you need platform portability or detailed snapshot comparison.
特性heaptrackValgrind massif
性能开销~2-3倍~20倍
输出形式压缩轨迹文件 + GUI文本/ms_print
泄漏检测支持支持
峰值跟踪支持支持
时间维度视图支持（GUI）支持（ms_print）
支持平台仅LinuxLinux、macOS
是否需要重编译否否
调用图完整调用栈完整调用栈
大多数场景下使用heaptrack；当需要跨平台兼容性或详细快照对比时，使用massif。

8. Integration with Rust

8. 与Rust的集成

heaptrack works with Rust binaries when using the system allocator:
rust
// Rust: use system allocator so heaptrack can intercept
use std::alloc::System;
#[global_allocator]
static A: System = System;
bash
undefined
当使用系统分配器时，heaptrack可用于Rust二进制文件：
rust
// Rust: 使用系统分配器以便heaptrack可以拦截
use std::alloc::System;
#[global_allocator]
static A: System = System;
bash
undefined

Profile Rust binary

分析Rust二进制文件

cargo build --release heaptrack ./target/release/myapp
cargo build --release heaptrack ./target/release/myapp

Note: debug symbols improve backtraces

注意：调试符号可提升回溯信息质量

cargo build --profile release-with-debug heaptrack ./target/release-with-debug/myapp

For heaptrack_print output reference and GUI usage, see [references/heaptrack-analysis.md](references/heaptrack-analysis.md).
cargo build --profile release-with-debug heaptrack ./target/release-with-debug/myapp

关于heaptrack_print输出参考和GUI使用方法，可查看[references/heaptrack-analysis.md](references/heaptrack-analysis.md)。

Related skills

相关技能

  • Use 
    skills/profilers/valgrind
    for Memcheck (correctness) and massif (alternative heap profiler)
  • Use 
    skills/profilers/linux-perf
    for CPU profiling alongside memory profiling
  • Use 
    skills/rust/rust-profiling
    for Rust-specific allocation profiling approaches
  • Use 
    skills/runtimes/sanitizers
    — ASan LeakSanitizer for leak detection without profiling overhead
  • 使用
    skills/profilers/valgrind
    进行Memcheck（正确性检查）和massif（替代堆分析工具）分析
  • 使用
    skills/profilers/linux-perf
    搭配内存分析进行CPU分析
  • 使用
    skills/rust/rust-profiling
    进行Rust专属的分配分析
  • 使用
    skills/runtimes/sanitizers
    —— ASan LeakSanitizer可在无分析开销的情况下检测泄漏