awfixers-stuff/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.

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?"

Workflow

1. Installation

# 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. Basic usage

# 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 for better profiling

# 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. Interpreting heaptrack_print output

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

Key sections:

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

| 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 |

5. Filtering and analysis options

# 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. Comparing two runs

# 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 vs Valgrind massif

| Feature | heaptrack | Valgrind massif | |---------|-----------|-----------------| | Overhead | ~2-3x | ~20x | | Output | Compressed trace + GUI | Text/ms_print | | Leak detection | Yes | Yes | | Peak tracking | Yes | Yes | | Temporal view | Yes (GUI) | Yes (ms_print) | | Platform | Linux only | Linux, macOS | | Needs recompile | No | No | | Call graph | Full stack traces | Full stack traces |

Use heaptrack for most cases; use massif when you need platform portability or detailed snapshot comparison.

8. Integration with Rust

heaptrack works with Rust binaries when using the system allocator:

// 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

For heaptrack_print output reference and GUI usage, see 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