Native Rust. One pass over the file. One self-contained binary.
- 10.2 GiB heap dump read
- 7.3 s median of 10 runs
- 1.4 GiB/s throughput
- 338 MiB peak memory
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.