//java architect /
HotSpot’s Hidden Treasure
The HotSpot Serviceability Agent’s powerful tools can debug live Java processes and core files.
POONAM BAJAJ
The HotSpot Serviceability Agent is a hidden treasure
present in the JDK that very
few people know about. The
Serviceability Agent (SA) is a set
of Java APIs and tools that can be
used to debug live Java processes
and core files (also called crash
dumps on Microsoft Windows).
SA can examine Java processes
or core files, which makes it suitable for debugging Java programs
as well as the Java HotSpot VM. It
is a snapshot debugger and lets
us look at the state of a frozen
Java process or a core file. When
SA is attached to a Java process,
it stops the process at that point
and we can explore the Java heap;
look at the threads that were running in the process at that point;
examine internal data structures
of the Java HotSpot VM; and look
at the loaded classes, compiled
code of methods, and so on.
The process resumes after SA is
detached from it.
tion SA binaries that are present in
the JDK. There are two SA binaries
that are shipped with the JDK:
■ ■ For Microsoft Windows:
sa-jdi.jar and jvm.dll
■ ■ For Oracle Solaris and Linux:
sa-jdi.jar and libsaproc.so
thread objects, and internal rep-
resentations of the Java HotSpot
VM. SA makes it very easy for us
to examine the Java-level details
and JVM-level details of the Java
process or core file.
JAVA IN ACTION
SA Debugging Tools
There are two main SA debugging
tools implemented using SA APIs:
■ ■ HSDB, which is a GUI tool and
the main debugger
■ ■ CLHSDB, which is a command-line variant of HSDB
HSDB: The GUI debugger. HSDB
facilitates examining Java processes, core files, and also remote
Java processes. Let’s see how
we can launch and use it on a
Microsoft Windows machine.
First, we need to set some environment variables. Set SA_JAVA to
the location of the Java executable
in the JDK/bin folder, for example:
ABOUT US
set SA_JAVA=
d:\java\jdk1.7.0_03\bin\java
blog
SA Binaries
Before we go into the details
about the features and utilities
that SA offers, I would like to men-
JDK Versions with Complete
SA Binaries
The following JDK versions have
complete SA binaries:
■ ■ JDK 7 on all platforms
■ ■ 6u17+ on Oracle Solaris and
Linux
■ ■ 6u31+ on Microsoft Windows
Linux. The JDK versions above make the
complete set of SA
classes available on all
of these platforms.
Why Use SA?
Why use SA when we have native
debugging tools such as dbx,
GDB, WinDbg, and many others?
First, SA is a Java-based,
platform-independent tool, so it
can be used to debug Java processes and cores on all the platforms where Java is supported.
Additionally, debugging a Java
process or the Java HotSpot VM
with native debuggers is very
limiting, because although native
debuggers can help us examine
the native OS process state, they
cannot help us examine the Java
or the Java Virtual Machine (JVM)
state of the process.
For example, if I need to view
the objects in the Java heap,
native debuggers would show me
the raw hex numbers,
whereas SA has the
ability to interpret
those hex numbers
and present the
object view instead.
SA has knowledge
about the Java heap,
such as its boundar-
ies, objects in the Java
heap, loaded classes,
SA makes it very easy
to examine the
Java-level details
and JVM-level
details of a Java
process or core file.
On Microsoft Windows, the
PATH environment variable should
contain the location of the JVM
binary used by the target pro-
