2N/A<html>
2N/A<head>
2N/A<title>
2N/AUsing HotSpot Serviceability Agent (SA)
2N/A</title>
2N/A</head>
2N/A<body>
2N/A<h1>Using HotSpot Serviceability Agent (SA)</h1>
2N/A
2N/A<h3>HSDB GUI</h3>
2N/A<p>
2N/AThe top-level GUI program using the HotSpot Serviceability Agent APIs is
2N/Acalled <b>HSDB</b>, the "HotSpot Debugger". To run it, type "hsdbproc.sh"
2N/Aor "hsdbwindbg.bat" or 64-bit variants (on Unix, Windows platforms
2N/Arespectively). More info. on HSDB GUI are in <a href="hsdb.html">hsdb.html</a>.
2N/A</p>
2N/A
2N/A<h3>SA Modes</h3>
2N/A<p>
2N/AThere are three modes for the SA debugger:
2N/A<ul>
2N/A<li>attaching to a local process,
2N/A<li>opening a core file, and
2N/A<li>attaching to a remote "debug server".
2N/A</ul>
2N/A<p>
2N/AThe remote case requires two programs to be running on the remote machine:
2N/Athe rmiregistry (see the script "start-rmiregistry.sh" in this directory;
2N/Arun this in the background) and the debug server (see the script
2N/A"start-debug-server-proc.sh"), in that order. start-rmiregistry.sh takes no
2N/Aarguments; start-debug-server-proc.sh (or -windbg.bat) takes as argument
2N/Athe process ID or the executable and core file names to allow remote debugging
2N/Aof.
2N/A</p>
2N/A
2N/A<h3>Command line HSDB</h3>
2N/A<p>
2N/AThere are also command line HSDB variants ("clhsdbproc.sh" or "clhsdbwindbg.bat"
2N/Aor 64-bit variants). There is also a JavaScript based command line interface
2N/Acalled "jsdbproc.sh" [or "jsdbwindbg.bat" or 64-bit variants]. More details on
2N/Acommand line interfaces can be found in
2N/A<ul>
2N/A<li><a href="clhsdb.html">clhsdb.html</a>
2N/A<li><a href="jsdb.html">jsdb.html</a>
2N/A</ul>
2N/A</p>
2N/A
2N/A<h3>Other command line tools</h3>
2N/A<p>
2N/AThe following table lists all SA command line tools. &lt;xxx&gt;windbg.bat
2N/Afiles are for Windows. .sh files are for Solaris. &lt;xxx&gt;64.sh are for
2N/A64 bit debugees.
2N/A</p>
2N/A
<table border="1">
<tr>
<th>
Tool
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
dumpflagsproc.sh,
dumpflagsproc64.sh,
dumpflagswindbg.bat
dumpflagswindbg64.bat
</td>
<td>
dumps name and value of all -XX JVM command line arguments passed
to debuggee.
</td>
</tr>
<tr>
<td>
<a name="dumpsysprops"></a>
dumpsyspropsproc.sh,
dumpsyspropsproc64.sh,
dumpsyspropswindbg.bat
dumpsyspropswindbg64.bat
</td>
<td>
This prints name and value of Java level System properties.
</td>
</tr>
<tr>
<td>
<a name="heapdump"></a>
heapdumpproc.sh,
heapdumpproc64.sh,
heapdumpwindbg.bat
heapdumpwindbg64.bat
</td>
<td>
Dumps heap in a file in hprof binary format.
</td>
</tr>
<tr>
<td>
<a name="heapsum"></a>
heapsumproc.sh,
heapsumproc64.sh,
heapsumwindbg.bat
heapsumwindbg64.bat
</td>
<td>
Prints summary information on Java heap.
</td>
</tr>
<tr>
<td>
jcoreproc.sh,
jcoreproc64.sh,
jcorewindbg.bat
jcorewindbg64.bat
</td>
<td>
This can retrieve .class files from the debuggee.
set the environment variable <b>JCORE_PACKAGES</b> to comman separated list of
packages whose classes have to be retrieved from the core file.
</td>
</tr>
<tr>
<tr>
<td>
jstackproc.sh,
jstackproc64.sh,
jstackwindbg.bat
jstackwindbg64.bat
</td>
<td>
used to get java stack trace for all java threads.
</td>
</tr>
<tr>
<td>
jhistoproc.sh,
jhistoproc64.sh,
jhistowindbg.bat
jhistowindbg64.bat
</td>
<td>
used to get object histogram of java heap.
</td>
</tr>
<tr>
<td>
permstatproc.sh,
permstatproc64.sh,
permstatwindbg.bat
permstatwindbg64.bat
</td>
<td>
To gather statistics on perm. generation.
</td>
</tr>
<a name="mixed_pstack"></a>
<tr>
<tr>
<td>
pstackproc.sh,
pstackproc64.sh,
pstackwindbg.bat
pstackwindbg64.bat
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
pmapproc.sh,
pmapproc64.sh,
pmapwindbg.bat
pmapwindbg64.bat
</td>
<td>
This is cross platform Solaris pmap-like utility.
</td>
</tr>
<tr>
<td>
soqlproc.sh,
soqlproc64.sh,
soqlwindbg.bat
soqlwindbg64.bat
</td>
<td>
This is command line SOQL - Simple Object Query Language tool.
SOQL is SQL-like query language to query Java heap.
</td>
<tr>
<td>
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
</td>
<td>
These scripts are used to run SA remotely.
</td>
</tr>
</table>
<h3>Debugging transported core dumps</h3>
<p>
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
<a href="transported_core.html">transported_core.html</a>.
</p>
<h3>SA Bugs</h3>
<p>
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.
</p>
</body>
</html>