jmap — heap histograms and heap dumps

Overview

jmap answers "what is filling the heap": a quick per-class histogram, or a full heap dump for offline analysis. Like jstack it is legacy spelling for what jcmd now does (GC.class_histogram, GC.heap_dump), but the workflow — histogram first, dump when you need object graphs — is the core of every memory-leak investigation.

Key points

• jmap -histo <pid>: instance count and shallow bytes per class, sorted descending; -histo:live first forces a full GC so only reachable objects count — comparing with/without live separates garbage-not-yet-collected from a real leak. Two histograms minutes apart show what grows.
• jmap -dump:live,format=b,file=heap.hprof <pid>: full hprof snapshot of the object graph. This is what you need for "who holds these objects" — histograms give sizes, dumps give paths to GC roots.
• Cost: a heap dump is a stop-the-world pause for the whole capture and writes roughly live-set-sized files — a 30 GB heap means a long freeze (seconds to minutes) and a 20–30 GB file. On production big heaps: dump on a node pulled from the load balancer, ensure disk space, or prefer JFR's OldObjectSample events for lower-impact leak hunting.
• Analysis tools: Eclipse MAT is the standard — dominator tree, "Leak Suspects" report, retained sizes, path-to-GC-roots; VisualVM opens hprof for lighter browsing. The dump contains all live data (passwords, PII included) — treat the file as sensitive.
• Automatic dumps: -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/dumps captures the heap at the moment of OOM — often the only dump that matters; set it everywhere.
• jcmd equivalents: jcmd <pid> GC.class_histogram and jcmd <pid> GC.heap_dump /path/heap.hprof (add -all to include unreachable objects). Same-user attach rule applies.

Examples

jmap -histo:live 4242 | head -20
jcmd 4242 GC.heap_dump /var/dumps/app-$(date +%s).hprof
# then open the .hprof in Eclipse MAT -> Leak Suspects

Related

• JDK & tools — parent catalogue of the JDK toolchain.
• jcmd — the modern spelling of both histogram and dump.
• jstack — the thread-side companion snapshot.
• JFR & Mission Control — OldObjectSample as the low-impact leak-hunting alternative.
• JVM memory anatomy — the heap areas and reference strengths a histogram is a snapshot of.
• Performance engineering — memory footprint as a performance concern.