0N/AUsing The HotSpot Serviceability Agent
0N/A<
BODY TEXT="#000000" BGCOLOR="#FFFFFF">
0N/AUsing The HotSpot Serviceability Agent
0N/A<
LI> <
A HREF = "#INTRODUCTION">Introduction</
A>
0N/A<
LI> <
A HREF = "#SOURCES">Organization of the sources</
A>
0N/A<
LI> <
A HREF = "#RUNNING">Running HSDB</
A>
0N/A<
LI> <
A HREF = "#NOTES">Notes</
A>
0N/A<
A NAME="INTRODUCTION">
0N/AThe HotSpot Serviceability Agent (SA) is a set of Java APIs which
0N/Amirror the internal APIs of the HotSpot VM and which can be used to
0N/Aexamine the state of a HotSpot VM.
0N/AThe system understands the layout of certain VM data structures and is
0N/Aable to traverse these structures in an examination-only fashion; that
0N/Ais, it does not rely on being able to run code in the target VM. For
0N/Athis reason it transparently works with either a running VM or a core
0N/AThe system can reconstruct information about Java frames on the stack
0N/Aand objects in the heap. Many of the important data structures in the
0N/AVM like the CodeCache, Universe, StubQueue, Frames, and VFrames have
0N/Abeen exposed and have relatively complete (or at least useful)
0N/AA small graphical debugger called HSDB (the "HotSpot Debugger") has
0N/Abeen written using these APIs. It provides stack memory dumps
0N/Aannotated with method invocations, compiled-code inlining (if
0N/Apresent), interpreted vs. compiled code, interpreter codelets (if
0N/Ainterpreted), and live oops from oop-map information. It also provides
0N/Aa tree-based oop inspector. More information will be added as
0N/Aemail</
A> with suggestions on what would be useful.
0N/AThe SA currently only works on Solaris. It uses dbx to connect to the
0N/Aremote process or core file and communicates with a small piece of
0N/Acode (an "import module") loaded into the debugger.
0N/AOrganization of the sources
0N/AThe Java-side source code, which is the bulk of the SA, is in
0N/Ahierarchy mirrors the organization in the VM. This should allow
0N/Aengineers familiar with the HotSpot sources to quickly understand how
0N/Athe SA works and to make modifications if necessary. To build these
0N/AThe SA on Solaris works by communicating with a small piece of code
0N/A(an "import module") loaded into dbx. The source code for this import
0N/Adistinction is necessary because the SPARC version of dbx ships with
0N/Atwo versions of its executable, and depending on which architecture
0N/A(v8 or v9) the debugger is running on selects the appropriate
0N/Aexecutable. The SA tries the v8 version first, but if you are running
0N/Aon a v9 machine you must provide both versions to the SA.
0N/AThe system is currently hardwired to look on jano for its dbx
0N/Aexecutable and import module. The relevant directory structure looks
0N/A <
LI> dbx: symlink to (v8) dbx 7.0 executable
0N/AThe code which builds up path names to these executables is contained
0N/Athis file to jano, but the rest of the system is isolated from this.
0N/A(It would be nice to have a panel in the debugger allowing
0N/Aconfiguration of all of the known operating systems' options; right
0N/Anow Solaris is the only supported OS, making that easier.)
0N/AAn installation of HSDB has been placed on jano. To access it, add the
0N/Afollowing directory to your PATH:
0N/ATo start the debugger, type "hsdb".
0N/AAlternatively, you can start a local build of the debugger by building
0N/AThere are three modes for the debugger: attaching to a local process,
0N/Aopening a core file, and attaching to a remote "debug server". The
0N/Aremote case requires two programs to be running on the remote machine:
0N/Athe rmiregistry (see the script "start-rmiregistry" in this directory;
0N/Arun this in the background) and the debug server (see the script
0N/A"start-debug-server"), in that order. start-rmiregistry takes no
0N/Aarguments; start-debug-server takes as argument the process ID or the
0N/Aexecutable and core file names to allow remote debugging of. Make sure
0N/Ayou do NOT have a CLASSPATH environment variable set when you run
0N/Athese scripts. (The classes put into the rmiregistry are in sun.*, and
0N/Athere are permissions problems if they aren't placed on the boot
0N/Apossible using the debug server; select "Connect to debug server..."
0N/AOnce the debugger has been launched, the threads list is displayed.
0N/AThe current set of functionality allows:
0N/A<
LI> Browsing of the annotated stack memory ("Stack Memory" button). It
0N/A is currently annotated with the following information:
0N/A <
LI> Method names of the Java frames and their extents (supporting
0N/A inlined compiled methods)
0N/A <
LI> Locations and types of oops, found using the oop map information
0N/A from compiled methods (interpreter oop maps coming soon)
0N/A <
LI> If a Java frame was interrupted by a signal (
e.g., because of a
0N/A crash), annotates the frame with the signal name and number
0N/A <
LI> Interpreter codelet descriptions for interpreted frames
0N/A<
LI> Finding which thread or threads caused a crash (currently
0N/A identified by the presence of a signal handler frame)
0N/A<
LI> Browsing of oops using the Oop Inspector.
0N/A<
LI> Object histogram and inspection of objects therein.
0N/AMore functionality is planned. Please <
A HREF = 0N/Awould be useful, with any questions or comments, or if the debugger
0N/AHSDB does not suspend the system at a safepoint, but at an arbitrary
0N/Apoint. This means that many of the invariants in the VM's code are not
0N/AAs it happens, most of the places where the code ported over from the
0N/AVM has failed involve the topmost frame on the stack. Some
0N/Amodifications have been made to allow the system to recognize
0N/Aproblematic situations.
0N/ACertainly, not all of the failure modes of the debugger have been
0N/AHSDB throws an exception. The best debugging aid in these situations
0N/Ais a core file since it is a static view of the VM to which we can
0N/Athen adapt the debugger code, as opposed to having to try to suspend
0N/Athe VM over and over to reproduce the failure. gcore (1) is a useful
0N/Atool. (NOTE: do not try gcore with any application using the DGA X
0N/Aserver extension (example: Java2Demo); the kernel will panic. See bug