Heap Dumps in Java

Introduction

In the Java Virtual Machine (JVM), the Heap is the runtime data area from which memory for all class instances and arrays is allocated. When an application behaves unexpectedly—especially when suffering from memory leaks, OutOfMemoryErrors, or sudden performance degradation—developers need a way to look inside the JVM's memory.

A Heap Dump is a snapshot of all the objects that are in memory in the JVM at a certain moment. Analyzing heap dumps is a critical skill for senior Java engineers diagnosing complex production issues.

What is Inside a Heap Dump?

A heap dump typically contains:

1. Objects: Class instances, their fields, primitive values, and references to other objects.
2. Classes: Classloaders, name of the classes, superclasses, and static fields.
3. Garbage Collection (GC) Roots: Objects that are accessible from outside the heap (like active threads, local variables in the thread stack, or system classes) which keep other objects alive.
4. Thread Data: Thread call stacks and local variables at the moment the snapshot was taken.

Note: Heap dumps usually do not contain allocation information (where the object was created) unless explicitly enabled via specific profiling tools.

Generating a Heap Dump

There are multiple ways to generate a heap dump, ranging from JVM flags to command-line utilities.

1. JVM Flags (The Proactive Approach)

The most common and recommended way to capture heap dumps in production is by configuring the JVM to automatically dump the heap when it runs out of memory.

java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/dumps/ myapp.jar

When an OutOfMemoryError (OOME) occurs, the JVM will write an .hprof file to the specified directory before crashing.

2. Using jcmd (The Modern Approach)

The jcmd utility is the recommended tool for sending diagnostic command requests to a running JVM.

# Find the PID of your Java process
jps

# Generate the heap dump
jcmd <PID> GC.heap_dump /path/to/dump.hprof

3. Using jmap (The Classic Approach)

Though slightly older, jmap is still widely used.

jmap -dump:live,format=b,file=/path/to/dump.hprof <PID>

Note: The :live option forces a full Garbage Collection before taking the dump, ensuring that only actively referenced objects are included.

4. JConsole / VisualVM

If you prefer a GUI, both Java VisualVM and JConsole allow you to connect to a running Java process and click a button to generate a heap dump.

Analyzing a Heap Dump

An .hprof file is a binary file. You cannot read it with a text editor. You need specialized tools to parse and analyze it.

Eclipse Memory Analyzer Tool (MAT)

Eclipse MAT is the industry standard for analyzing Java heap dumps.

• Leak Suspects Report: Automatically analyzes the dump to find memory leaks and identifies the objects accumulating memory.
• Dominator Tree: Shows you the biggest objects in the heap. If a node is removed from the tree, all its children can be garbage collected.

VisualVM

VisualVM provides a built-in heap dump viewer. While not as powerful as MAT for massive, multi-gigabyte dumps, it is excellent for quick, high-level investigations, allowing you to browse classes and instance counts easily.

Common Scenarios to Look For

When analyzing a heap dump, keep an eye out for these common memory leak patterns:

1. Unintentional Static References: Collections (like HashMap or ArrayList) declared as static that are continuously added to but never cleared.
2. ThreadLocal Variables: Objects stored in ThreadLocal that are never removed (ThreadLocal.remove()), especially in thread pools (like Tomcat worker threads).
3. Unclosed Resources: Streams, database connections, or network sockets that are opened but not properly closed in a finally block or try-with-resources.
4. Cache Without Eviction: Implementing a custom cache without an eviction policy (like an LRU cache or weak references).

Summary

Heap dumps are the ultimate source of truth when diagnosing Java memory issues. By ensuring your applications run with -XX:+HeapDumpOnOutOfMemoryError and mastering tools like Eclipse MAT, you can confidently track down and eliminate even the most elusive memory leaks in production environments.