LinuxCommandLibrary

jmap

Dump Java heap memory information

TLDR

Print shared object mappings for a Java process (output like pmap)

$ jmap [java_pid]
copy

Print heap summary information
$ jmap -heap [filename.jar] [java_pid]
copy

Print histogram of heap usage by type
$ jmap -histo [java_pid]
copy

Dump contents of the heap into a binary file for analysis with jhat
$ jmap -dump:format=b,file=[path/to/file] [java_pid]
copy

Dump live objects of the heap into a binary file for analysis with jhat
$ jmap -dump:live,format=b,file=[path/to/file] [java_pid]
copy

SYNOPSIS

jmap [options] pid
jmap [options] executable core
jmap [options] server-id@remote-ip-or-hostname

PARAMETERS

-heap
    Displays a summary of the Java heap, including information about garbage collection (GC) configuration and memory usage.

-histo[:live]
    Prints a histogram of the heap, showing the total size and instance count for each Java class. The optional live sub-option counts only live objects.

-dump:
    Dumps the Java heap into a specified file. Common dump-options include format=b (for binary HPROF format) and file=<filename> (to specify the output file path). The live sub-option can be used to dump only live objects.

-clstats
    Prints statistics about the class loaders and the objects they load.

-finalizerinfo
    Displays information about objects that are waiting for finalization.

pid
    The process ID of the running Java Virtual Machine (JVM) for which to obtain memory information.

executable
    (Optional) The path to the Java executable if analyzing a core dump.

core
    (Optional) The path to the core dump file to analyze.

server-id@remote-ip-or-hostname
    (Optional) Connects to a remote debug server for analysis, specified by an ID and a hostname or IP address.

DESCRIPTION

jmap is a command-line utility provided with the Java Development Kit (JDK). It's designed to print shared object memory maps or detailed heap memory statistics for a running Java Virtual Machine (JVM) process. This tool is invaluable for diagnosing memory-related issues such as memory leaks, analyzing the overall memory consumption of a Java application, and understanding the distribution of objects within the Java heap.

By connecting to a specified Java process via its process ID (PID), jmap can provide insights into object sizes, instance counts, and classloader information. It's often used in conjunction with other JDK tools like jstat and jstack for comprehensive JVM monitoring and troubleshooting.

CAVEATS

Using jmap, particularly with the -dump option, can temporarily pause the target JVM, potentially affecting application performance. It requires appropriate user permissions (same user as the JVM process or root). In newer JDK versions (JDK 9+), jmap is often recommended to be used via jhsdb jmap for certain functionalities, and some of its standalone options for printing shared object memory maps have been deprecated or their behavior has changed, with jhsdb being the preferred tool for post-mortem analysis.

HEAP DUMP ANALYSIS

Heap dumps generated by jmap (especially with -dump:format=b) are typically in HPROF binary format. These files can be loaded into specialized memory analysis tools like Eclipse Memory Analyzer (MAT), VisualVM, or YourKit Java Profiler to visualize object graphs, identify memory leaks, analyze shallow vs. retained sizes, and understand object distribution in detail.

PERMISSIONS

To successfully execute jmap against a running Java process, the user executing the jmap command must have sufficient permissions to inspect the target Java process. This typically means running as the same user that started the Java application or as the root user. Without proper permissions, jmap will fail to attach to the JVM.

HISTORY

jmap has been a standard utility within the Java Development Kit (JDK) since early versions, notably from Java 5 onwards. Its core functionality of providing heap and memory statistics has remained consistent. With the introduction of JDK 9, the jhsdb tool was introduced, aiming to unify and supersede some of the standalone diagnostic commands like jmap, jstack, and jinfo, especially for attaching to processes and analyzing core dumps. While jmap continues to function as a direct command, its usage often overlaps with jhsdb for advanced debugging and post-mortem analysis in more recent JDK environments.

SEE ALSO

jstack(1), jstat(1), jcmd(1), jhsdb(1), pmap(1)

Copied to clipboard