hprof-slurp analyze JVM heap dumps larger than your RAM

Point it at an hprof file and get the classes taking the most heap, their instance counts and largest objects, plus a thread dump of what every thread was running, in seconds. One streaming pass with bounded memory, so a dump bigger than the machine reading it is fine. Compare two dumps to find what leaks.

macOS · Linux

curl -fsSL https://agourlay.github.io/hprof-slurp/install.sh | sh

Installs to ~/.local/bin · Read the script

Windows (PowerShell)

irm https://raw.githubusercontent.com/agourlay/hprof-slurp/master/site/install.ps1 | iex

Installs to %LOCALAPPDATA%\Programs and adds it to your PATH · Read the script

Or with Rust: cargo install hprof-slurp · download a release

$ hprof-slurp heap.hprof --top 8
Processing 10.17GiB binary hprof file in 'JAVA PROFILE 1.0.2' format.
…
Found a total of 9.27GiB of raw shallow heap objects in the dump.

Top 8 raw shallow heap classes:

+------------+-----------+------------+--------------------------+
| Total size | Instances |    Largest | Class name               |
+------------+-----------+------------+--------------------------+
|    2.52GiB |  77411664 |   37.41KiB | byte[]                   |
|    2.31GiB |  77353946 | 32.00bytes | java.lang.String         |
|    1.32GiB |  29466082 | 48.00bytes | java.util.HashMap$Node   |
|    1.10GiB |  14735098 |  391.62KiB | int[]                    |
|  674.30MiB |  14730360 | 48.00bytes | HeapFiller$Order         |
|  505.86MiB |   3683023 |   64.02KiB | java.util.HashMap$Node[] |
|  383.05MiB |   3689688 |   31.30MiB | java.lang.Object[]       |
|  224.79MiB |   3683036 | 64.00bytes | java.util.HashMap        |
+------------+-----------+------------+--------------------------+
…
File successfully processed in 7.050728043s

Native Rust. One pass over the file. One self-contained binary.

OpenJDK 24 dump of 232 million objects, on an AMD Ryzen AI 9 HX PRO 370 with the file in the page cache. Memory is set by fixed 64 MiB read buffers, the per-class tables and the largest single object, not by the size of the dump.

Bigger than RAM

The dump is streamed once, front to back, through a few fixed buffers. Nothing is indexed or spilled to disk, so a dump several times larger than the machine's RAM reads fine.

JVM and Android

HotSpot dumps from jcmd or jmap, 32 or 64-bit, and Android dumps from ART and Dalvik with their extension records, read as they are: no hprof-conv step.

Made for CI

The report goes to stdout and progress to stderr. Add --json for scripts, and gate a build on heap growth with diff, which exits with code 2 over budget.

What the report covers

One run prints a summary of the dump's records, a thread dump, then two tables: the classes holding the most shallow heap, and the classes with the largest single instances.

Top classes

Total shallow size, instance count and largest instance per class, arrays included.

$ hprof-slurp heap.hprof --top 50

Thread dump

The stack of every thread at the moment of the dump, frame by frame with source file and line: what the process was doing when it was captured. Printed on every run.

Stack trace 3 (thread 3)
  at java.lang.Object.wait0 (Object.java:native method)
  at java.lang.Object.wait (Object.java:389)
  at java.lang.Object.wait (Object.java:351)
  at java.lang.ref.ReferenceQueue.remove0 (ReferenceQueue.java:138)
  at java.lang.ref.ReferenceQueue.remove (ReferenceQueue.java:229)
  at java.lang.ref.Finalizer$FinalizerThread.run (Finalizer.java:165)

Focus on your code

Keep the classes whose name contains a text; the dump-wide total and the selection's share stay in view.

$ hprof-slurp heap.hprof --filter com.example

JSON for scripts

Dump metadata, totals and both top lists as a versioned JSON document, next to the text report.

$ hprof-slurp heap.hprof --json -o report.json

String table

The names the dump is written with: classes, methods, fields and signatures. Duplicates are counted on every run; print them all with --list-strings.

$ hprof-slurp heap.hprof --list-strings

Find what grows with diff

A single dump shows what is big; two dumps of the same process show what keeps growing. diff lists the per-class change in shallow size and instance count, largest growth first. Here, a cache that never evicts, dumped at 20,000 and 200,000 sessions:

$ hprof-slurp diff before.hprof after.hprof --top 6 --fail-over 10MiB

Heap diff of raw shallow sizes:
  from: before.hprof (24.26MiB)
  to:   after.hprof (199.87MiB)
  net:  +175.61MiB

Top 6 of 276 class deltas (by shallow size growth):

      Δ size  Δ instances        size (from → to) instances (from → to)  Class name
   +32.96MiB     +1080012      4.26MiB → 37.22MiB      139502 → 1219514  java.lang.String
   +28.47MiB      +180000      3.13MiB → 31.60MiB        20434 → 200434  java.util.HashMap$Node[]
   +27.47MiB     +1080012      4.11MiB → 31.58MiB      139679 → 1219691  byte[]
   +24.72MiB      +540000      2.99MiB → 27.71MiB        65362 → 605362  java.util.HashMap$Node
   +20.60MiB      +540000      2.29MiB → 22.89MiB        60000 → 600000  SessionCache$Order
   +16.48MiB      +180000      2.32MiB → 18.80MiB        23449 → 203449  java.lang.Object[]
net shallow heap growth is over the --fail-over threshold
$ echo $?
2

Gate a build on heap growth

--fail-over takes a budget in bytes or with a unit. Over it, the run exits with 2; a run that could not complete exits with 1, so a CI job can tell the two apart. With --filter, only the selected classes count against the budget.

# .github/workflows/soak.yml
- name: Heap growth under budget
  run: |
    hprof-slurp diff baseline.hprof soak.hprof \
      --filter com.example --fail-over 50MiB \
      --json -o heap-diff.json

Shallow sizes, on purpose

Reading a dump in one pass is what makes huge dumps cheap, and it decides what can be measured.

Shallow, not retained

Each object counts its own header and fields, not what it references. Retained sizes, dominator trees and paths to GC roots need the whole object graph in memory, which is what this tool is built to avoid. When you need them, use the top classes here to know where to look, then open the dump in Eclipse MAT or VisualVM.

Tips & common questions

How do I take a heap dump?

On a running JVM, jcmd <pid> GC.heap_dump /tmp/heap.hprof (or jmap -dump:live,format=b,file=/tmp/heap.hprof <pid>). To catch the moment it runs out, start it with -XX:+HeapDumpOnOutOfMemoryError. On Android, adb shell am dumpheap <process> /data/local/tmp/app.hprof then adb pull it; the file can be read directly.

How much memory does it need?

A few hundred MiB on a large dump: 338 MiB at peak on the 10 GiB dump above. The read buffers are fixed in size, and what grows is one small entry per class, name and stack frame, not one per object, so a dump of several times your RAM is fine. The one exception is a single object larger than a buffer, such as a huge array: it is held whole while it is read.

How are the sizes computed?

They are estimated from the class layouts recorded in the dump, the way Eclipse MAT does it: an object header plus the fields of the class and of each superclass, padded to 8 bytes, and for arrays a header plus the elements. A 64-bit HotSpot dump always records 8-byte references, so for a JVM running with compressed references the sizes are an upper bound. They are best read relative to each other, or across two dumps.

Can I diff a 32-bit dump against a 64-bit one?

It runs, but the report ends with a warning: object headers and references have different sizes on each side, so part of every delta comes from the pointer width and not from the heap. Compare dumps of the same process, taken the same way.

The dump was still being copied. Will it notice?

Yes. A file that ends in the middle of a record or of a heap dump segment fails with the file is truncated and exit code 1, instead of reporting the part that was read as if it were the whole heap.

Where do I learn how it works?

The design, from the streaming parser to the pipeline of threads, is described in a series of blog articles.