heaptrail user guide

Find what is holding your memory

heaptrail reads JVM and Android heap dumps from the command line. It ranks what takes the space, traces what keeps an object alive, and compares snapshots. Most modes stream the file instead of loading it, so a 224 MiB Android dump takes about a fifth of a second on a laptop. Output is plain text, with JSON for scripts and CI.

Start your first triage Install heaptrail

heaptrail

$ heaptrail -i heap.hprof --leak-suspects --exclude-soft-weak --top 1

Suspect 1 — 27.98MiB (26.2 % of heap)
  dominator: java.util.ArrayList (object_id=361762400)
  accumulating: 262517 instances of com.nexio.tv.domain.model.MetaPreview, total 26.04MiB
  path to GC root:

  Path from object_id=361762400 (depth 12 step(s)):
    start  ── id=361762400
    ...
    hop 3 ── id=361760584  (via com.nexio.tv.ui.screens.home.HomeViewModel.fullCatalogRows)
    ...
    hop 6 ── id=327606088  (via androidx.lifecycle.ViewModelStore.map)
    ...
    hop 9 ── id=327605632  (via androidx.navigation.NavControllerViewModel.viewModelStores)

A command-line tool

heaptrail has no window to click through. Each investigation is one command that prints a report you can read in a terminal, paste into a ticket, or parse with jq. For interactive graph browsing, use Eclipse MAT after heaptrail has narrowed the question.

What do you want to do?

• Get a heap dump

  ---

  Capture from an Android device with one command, or from a running JVM with jmap. Check that the file is whole before you analyze it.

  Capture

  Popular: android-capture · JVM dumps

• See what is using memory

  ---

  Rank classes by size, find the objects that keep the most alive, and let heaptrail name the likely leak suspects.

  Analyze

  Popular: Summary · Leak suspects

• Find what holds an object

  ---

  Follow a class or a single object back to the field, array or static that keeps it alive, all the way to a GC root.

  Trace holders

  Popular: Find referrers · Paths to a GC root

• Check whether memory grows

  ---

  Compare two snapshots, or a whole timeline of three or more, and pick out the classes that only ever get bigger.

  Compare

  Popular: Snapshot diff · Diff a series

• Read an Android release build

  ---

  Turn names like a3.t back into real class names with your R8 mapping file, chosen by hand or matched to the installed app.

  Android

  Popular: Deobfuscate · Auto-mapping

• Look inside big arrays

  ---

  A 5 MiB char[] is not a diagnosis. Preview what it holds: JSON, XML, an image, or a buffer full of zeros.

  Content previews

  Popular: Identify a giant array · Find duplicate payloads

• Script it or hand it to an agent

  ---

  Write stable JSON files, gate a build on a leak threshold, or let Claude Code run the whole triage for you.

  Automate

  Popular: JSON output · CI gates

• Understand the numbers

  ---

  Shallow versus retained size, GC roots, weak references and object ids, explained once and linked from everywhere else.

  Concepts

  Popular: Shallow and retained size · GC roots and paths

• Look something up

  ---

  Every flag, which flags combine, the JSON fields, error messages and exit codes, and how fast each mode runs.

  Reference

  Popular: Command line · Errors and exit codes

New here?

1. Install heaptrail with cargo install heaptrail or a prebuilt binary.
2. Work through Your first triage, a real investigation from the first summary to the field that causes the leak.
3. Keep Choose the right mode open: it maps the question you have to the command that answers it.

No heap dump of your own yet? Follow along with the files in the repository.

When to use heaptrail, and when not to

Reach for heaptrail when…	Reach for Eclipse MAT or VisualVM when…
You want a first answer in seconds, from a terminal or a script.	You want to click through references and pivot as you go.
The dump is large, or the machine is a CI runner or a remote box.	You need OQL, or an HTML report for people who will not open a terminal.
An agent or a pipeline should read the result.	You are doing an open-ended, exploratory session.

The two work well together. Use heaptrail to narrow the question, then open the dump in MAT if you need a graph session.

Use the search box (press S or /) to find a flag, an error message or a class name.

Get help and follow changes

Read what changed in each release in What's new, or on the GitHub releases page. If a step in this guide differs from your build, report it on GitHub with your heaptrail version (heaptrail --version), your operating system and the command you ran.