heaptrack

heaptrack

目的

Linux でのヒープ割り当てプロファイリングに heaptrack を使用する方法をエージェントに案内します。割り当てトレースの記録、heaptrack_print による分析、リークやホットスポットの特定、実行結果の比較を扱います。

利用のきっかけ

• 「C++ プログラムのメモリ割り当てのホットスポットを見つけるにはどうすればよいですか？」
• 「プログラムのメモリ使用量が多すぎます。原因箇所を見つけるにはどうすればよいですか？」
• 「heaptrack でメモリリークを検出するにはどうすればよいですか？」
• 「heaptrack とは何ですか？ Valgrind massif とはどう違いますか？」
• 「プログラムの 2 つのバージョン間でメモリ使用量を比較するにはどうすればよいですか？」
• 「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	1 つのコールスタック内で割り当てられ、解放されたメモリ
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. 2 つの実行結果の比較

# 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～3 倍	約 20 倍
出力	圧縮トレース + 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 を参照してください。

関連スキル

• Memcheck（正確性の検証）と massif（代替のヒーププロファイラー）には skills/profilers/valgrind を使用します
• メモリプロファイリングと併せて CPU プロファイリングを行うには skills/profilers/linux-perf を使用します
• Rust 固有の割り当てプロファイリング手法には skills/rust/rust-profiling を使用します
• プロファイリングのオーバーヘッドなしでリークを検出する ASan LeakSanitizer には skills/runtimes/sanitizers を使用します