| <html> |
| <head> |
| <title> |
| Using HotSpot Serviceability Agent (SA) |
| </title> |
| </head> |
| <body> |
| <h1>Using HotSpot Serviceability Agent (SA)</h1> |
| |
| <h3>HSDB GUI</h3> |
| <p> |
| The top-level GUI program using the HotSpot Serviceability Agent APIs is |
| called <b>HSDB</b>, 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 <a href="hsdb.html">hsdb.html</a>. |
| </p> |
| |
| <h3>SA Modes</h3> |
| <p> |
| There are three modes for the SA debugger: |
| <ul> |
| <li>attaching to a local process, |
| <li>opening a core file, and |
| <li>attaching to a remote "debug server". |
| </ul> |
| <p> |
| 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. |
| </p> |
| |
| <h3>Command line HSDB</h3> |
| <p> |
| 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 |
| <ul> |
| <li><a href="clhsdb.html">clhsdb.html</a> |
| <li><a href="jsdb.html">jsdb.html</a> |
| </ul> |
| </p> |
| |
| <h3>Other command line tools</h3> |
| <p> |
| 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. |
| </p> |
| |
| <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>C2 Compilation Replay</h3> |
| <p> |
| 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. |
| <a href="c2replay.html">c2replay.html</a> |
| |
| <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> |
