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