# Using HotSpot Serviceability Agent (SA)

### HSDB GUI

The top-level GUI program using the HotSpot Serviceability Agent APIs is called HSDB, the "HotSpot Debugger". To run it, type "hsdbproc.sh" or "hsdbwindbg.bat" or 64-bit variants (on Unix, Windows platforms respectively). More info. on HSDB GUI are in hsdb.html.

### SA Modes

There are three modes for the SA debugger:

- attaching to a local process,
- opening a core file, and
- attaching to a remote "debug server".

The remote case requires two programs to be running on the remote machine: the rmiregistry (see the script "start-rmiregistry.sh" in this directory; run this in the background) and the debug server (see the script "start-debug-server-proc.sh"), in that order. start-rmiregistry.sh takes no arguments; start-debug-server-proc.sh (or -windbg.bat) takes as argument the process ID or the executable and core file names to allow remote debugging of.

### Command line HSDB

There are also command line HSDB variants ("clhsdbproc.sh" or "clhsdbwindbg.bat" or 64-bit variants). There is also a JavaScript based command line interface called "jsdbproc.sh" [or "jsdbwindbg.bat" or 64-bit variants]. More details on command line interfaces can be found in

- clhsdb.html
- jsdb.html

### Other command line tools

The following table lists all SA command line tools. <xxx>windbg.bat files are for Windows. .sh files are for Solaris. <xxx>64.sh are for 64 bit debugees.

Tool | Description
--- | ---
dumpflagsproc.sh, dumpflagsproc64.sh, dumpflagswindbg.bat dumpflagswindbg64.bat | dumps name and value of all -XX JVM command line arguments passed to debuggee.
dumpsyspropsproc.sh, dumpsyspropsproc64.sh, dumpsyspropswindbg.bat dumpsyspropswindbg64.bat | This prints name and value of Java level System properties.
heapdumpproc.sh, heapdumpproc64.sh, heapdumpwindbg.bat heapdumpwindbg64.bat | Dumps heap in a file in hprof binary format.
heapsumproc.sh, heapsumproc64.sh, heapsumwindbg.bat heapsumwindbg64.bat | Prints summary information on Java heap.
jcoreproc.sh, jcoreproc64.sh, jcorewindbg.bat jcorewindbg64.bat | This can retrieve .class files from the debuggee. set the environment variable JCORE_PACKAGES to comman separated list of packages whose classes have to be retrieved from the core file.
jstackproc.sh, jstackproc64.sh, jstackwindbg.bat jstackwindbg64.bat | used to get java stack trace for all java threads.
jhistoproc.sh, jhistoproc64.sh, jhistowindbg.bat jhistowindbg64.bat | used to get object histogram of java heap.
permstatproc.sh, permstatproc64.sh, permstatwindbg.bat permstatwindbg64.bat | To gather statistics on perm. generation.
pstackproc.sh, pstackproc64.sh, pstackwindbg.bat pstackwindbg64.bat | This is cross platform mixed mode pstack utility. This works on any (non-java as well) process, core dump. For java process and core dumps, this prints both java and C/C++ frames.
pmapproc.sh, pmapproc64.sh, pmapwindbg.bat pmapwindbg64.bat | This is cross platform Solaris pmap-like utility.
soqlproc.sh, soqlproc64.sh, soqlwindbg.bat soqlwindbg64.bat | This is command line SOQL - Simple Object Query Language tool. SOQL is SQL-like query language to query Java heap.
start-debug-server-proc.sh, start-debug-server-proc64.sh, start-debug-server-windbg.bat, start-debug-server-windbg64.bat, start-rmiregistry.bat, start-rmiregistry64.bat, start-rmiregistry.sh start-rmiregistry64.sh | These scripts are used to run SA remotely.

### C2 Compilation Replay

When a java process crashes in compiled method, usually a core file is saved. The C2 replay function can reproduce the compiling process in the core. c2replay.html

### Debugging transported core dumps

When a core dump is moved from the machine where it was produced to a difference machine, it may not always be possible for SA to debug the same. More info. on debugging on transported core dumps is in transported_core.html.

### SA Bugs

Not all of the possible states of target VMs have been tested (or supportable) with SA. For example, the SA will probably not work at all if it freezes the target VM during certain phases of GC. When filing bugs a pointer to a core file (see gcore(1)) which the SA can not handle well is best.