LinuxCommandLibrary

jhsdb

Debug Java processes and core dumps

TLDR

Print stack and locks information of a Java process

$ jhsdb jstack --pid [pid]
copy

Open a core dump in interactive debug mode
$ jhsdb clhsdb --core [path/to/core_dump] --exe [path/to/jdk/bin/java]
copy

Start a remote debug server
$ jhsdb debugd --pid [pid] --serverid [optional_unique_id]
copy

Connect to a process in interactive debug mode
$ jhsdb clhsdb --pid [pid]
copy

SYNOPSIS

jhsdb <subcommand> [<options>] [<pid> | <executable> <core_file>]

Common Subcommands:
jhsdb debugd [-debug] [-client | -server] <pid>
jhsdb hsdb [-debug] [-client | -server] [<pid> | <executable> <core_file>]
jhsdb jstack [-exe <executable>] [-core <core_file>] [-l] [-e] [-m] [-F] [<pid>]
jhsdb jinfo [-sysprops] [-flags] [-l] [-e] [<pid> | <executable> <core_file>]
jhsdb jmap [-heap] [-histo] [-dump:<options>] [<pid> | <executable> <core_file>]
jhsdb jsync [<pid> | <executable> <core_file>]
jhsdb clrstat

PARAMETERS

debugd
    Launches a HotSpot Serviceability Agent (SA) debug server. Used for remotely debugging Java applications or analyzing core dumps, allowing other SA clients (like another jhsdb instance or a GUI debugger) to connect.

hsdb
    Launches the HotSpot Debugger. This subcommand provides either a command-line or graphical debugger (if supported by the environment) for inspecting the internal state of a running JVM or analyzing a core dump. It's the primary interactive interface for SA tools.

jstack
    Prints Java thread stack traces for the specified Java process or core file. Useful for diagnosing deadlocks, long-running operations, or unresponsive applications. Options like '-l' provide more detail on locks.

jinfo
    Prints Java configuration information for a specified process or core file. This includes Java system properties, JVM command-line flags, and other environment details. Useful for verifying JVM settings.

jmap
    Prints memory-related statistics for a Java process or core file. It can show heap usage, object counts, or dump the heap to a file for offline analysis with tools like Eclipse Memory Analyzer. Options like '-heap' and '-histo' are common.

jsync
    Prints Java thread synchronization information for a specified process or core file. This can help identify issues related to monitor contention and synchronization blocks.

clrstat
    Clears internal HotSpot VM performance counter statistics. This is primarily used in development or testing scenarios to reset VM counters without restarting the process.

DESCRIPTION

jhsdb is a powerful command-line utility in the Java Development Kit (JDK) for debugging and analyzing Java HotSpot Virtual Machines. Introduced in JDK 9, it consolidates the functionalities of several older tools like hsdb and jsadebugd, providing a unified interface for the HotSpot Serviceability Agent (SA) tools.

This tool is essential for advanced troubleshooting, post-mortem analysis of core dumps, and live debugging of Java processes. It allows developers and administrators to inspect the internal state of a running JVM or a core dump, providing insights into threads, memory, classloaders, and other low-level VM structures. Its subcommands enable various diagnostic tasks, from printing thread stack traces (similar to jstack) and heap summaries (similar to jmap) to launching a full debugger UI (hsdb) or a remote debugging server (debugd). It's crucial for diagnosing complex issues like deadlocks, memory leaks, or native crashes within the JVM.

CAVEATS

jhsdb requires appropriate permissions to attach to a running process or read a core dump. On Linux, this often means running as root or with sudo, or ensuring the user has necessary capabilities (e.g., via ptrace permissions).

Analyzing core dumps typically requires the original executable that generated the core dump, especially for complex scenarios or if debugging symbols are needed. The effectiveness of jhsdb relies on the presence of these symbols, which might be stripped in production environments.

While powerful, jhsdb is primarily designed for advanced users, VM developers, and experienced troubleshooters due to its low-level nature and the complexity of the information it provides.

SERVICEABILITY AGENT (SA)

jhsdb is built upon the HotSpot Serviceability Agent (SA) framework. The SA is a Java library that provides an API for inspecting the internal state of a running HotSpot JVM or a core dump. It's an out-of-process tool, meaning it doesn't run within the target JVM, preventing interference with the application being debugged.

CORE DUMP ANALYSIS

One of the most powerful features of jhsdb is its ability to perform post-mortem analysis on Java process core dumps. This allows for detailed investigation of application and JVM state at the time of a crash, without affecting a live production system. Ensure the core dump includes the necessary JVM memory regions.

HISTORY

jhsdb was introduced in JDK 9 as part of a significant modularization effort and consolidation of diagnostic tools. Prior to JDK 9, the functionalities now encompassed by jhsdb were provided by separate tools such as hsdb (the HotSpot Debugger) and jsadebugd (the Serviceability Agent debug server).

The motivation behind jhsdb was to provide a single, consistent command-line interface for the HotSpot Serviceability Agent (SA) tools, making it easier for users to access and utilize these powerful low-level debugging and analysis capabilities without needing to learn multiple commands.

SEE ALSO

jstack(1), jmap(1), jinfo(1), jcmd(1), gdb(1), hsdb(1), jsadebugd(1)

Copied to clipboard