1
+ − 1 <html>
+ − 2 <head>
+ − 3 <title>
+ − 4 Using HotSpot Serviceability Agent (SA)
+ − 5 </title>
+ − 6 </head>
+ − 7 <body>
+ − 8 <h1>Using HotSpot Serviceability Agent (SA)</h1>
+ − 9
+ − 10 <h3>HSDB GUI</h3>
+ − 11 <p>
+ − 12 The top-level GUI program using the HotSpot Serviceability Agent APIs is
+ − 13 called <b>HSDB</b>, the "HotSpot Debugger". To run it, type "hsdbproc.sh"
+ − 14 or "hsdbwindbg.bat" or 64-bit variants (on Unix, Windows platforms
+ − 15 respectively). More info. on HSDB GUI are in <a href="hsdb.html">hsdb.html</a>.
+ − 16 </p>
+ − 17
+ − 18 <h3>SA Modes</h3>
+ − 19 <p>
+ − 20 There are three modes for the SA debugger:
+ − 21 <ul>
+ − 22 <li>attaching to a local process,
+ − 23 <li>opening a core file, and
+ − 24 <li>attaching to a remote "debug server".
+ − 25 </ul>
+ − 26 <p>
+ − 27 The remote case requires two programs to be running on the remote machine:
+ − 28 the rmiregistry (see the script "start-rmiregistry.sh" in this directory;
+ − 29 run this in the background) and the debug server (see the script
+ − 30 "start-debug-server-proc.sh"), in that order. start-rmiregistry.sh takes no
+ − 31 arguments; start-debug-server-proc.sh (or -windbg.bat) takes as argument
+ − 32 the process ID or the executable and core file names to allow remote debugging
+ − 33 of.
+ − 34 </p>
+ − 35
+ − 36 <h3>Command line HSDB</h3>
+ − 37 <p>
+ − 38 There are also command line HSDB variants ("clhsdbproc.sh" or "clhsdbwindbg.bat"
+ − 39 or 64-bit variants). There is also a JavaScript based command line interface
+ − 40 called "jsdbproc.sh" [or "jsdbwindbg.bat" or 64-bit variants]. More details on
+ − 41 command line interfaces can be found in
+ − 42 <ul>
+ − 43 <li><a href="clhsdb.html">clhsdb.html</a>
+ − 44 <li><a href="jsdb.html">jsdb.html</a>
+ − 45 </ul>
+ − 46 </p>
+ − 47
+ − 48 <h3>Other command line tools</h3>
+ − 49 <p>
+ − 50 The following table lists all SA command line tools. <xxx>windbg.bat
+ − 51 files are for Windows. .sh files are for Solaris. <xxx>64.sh are for
+ − 52 64 bit debugees.
+ − 53 </p>
+ − 54
+ − 55 <table border="1">
+ − 56 <tr>
+ − 57 <th>
+ − 58 Tool
+ − 59 </th>
+ − 60 <th>
+ − 61 Description
+ − 62 </th>
+ − 63 </tr>
+ − 64
+ − 65 <tr>
+ − 66 <td>
+ − 67 dumpflagsproc.sh,
+ − 68 dumpflagsproc64.sh,
+ − 69 dumpflagswindbg.bat
+ − 70 dumpflagswindbg64.bat
+ − 71 </td>
+ − 72 <td>
+ − 73 dumps name and value of all -XX JVM command line arguments passed
+ − 74 to debuggee.
+ − 75 </td>
+ − 76 </tr>
+ − 77
+ − 78 <tr>
+ − 79 <td>
+ − 80 <a name="dumpsysprops"></a>
+ − 81 dumpsyspropsproc.sh,
+ − 82 dumpsyspropsproc64.sh,
+ − 83 dumpsyspropswindbg.bat
+ − 84 dumpsyspropswindbg64.bat
+ − 85 </td>
+ − 86 <td>
+ − 87 This prints name and value of Java level System properties.
+ − 88 </td>
+ − 89 </tr>
+ − 90
+ − 91 <tr>
+ − 92 <td>
+ − 93 <a name="heapdump"></a>
+ − 94 heapdumpproc.sh,
+ − 95 heapdumpproc64.sh,
+ − 96 heapdumpwindbg.bat
+ − 97 heapdumpwindbg64.bat
+ − 98 </td>
+ − 99 <td>
+ − 100 Dumps heap in a file in hprof binary format.
+ − 101 </td>
+ − 102 </tr>
+ − 103
+ − 104 <tr>
+ − 105 <td>
+ − 106 <a name="heapsum"></a>
+ − 107 heapsumproc.sh,
+ − 108 heapsumproc64.sh,
+ − 109 heapsumwindbg.bat
+ − 110 heapsumwindbg64.bat
+ − 111 </td>
+ − 112 <td>
+ − 113 Prints summary information on Java heap.
+ − 114 </td>
+ − 115 </tr>
+ − 116
+ − 117
+ − 118 <tr>
+ − 119 <td>
+ − 120 jcoreproc.sh,
+ − 121 jcoreproc64.sh,
+ − 122 jcorewindbg.bat
+ − 123 jcorewindbg64.bat
+ − 124 </td>
+ − 125 <td>
+ − 126 This can retrieve .class files from the debuggee.
+ − 127 set the environment variable <b>JCORE_PACKAGES</b> to comman separated list of
+ − 128 packages whose classes have to be retrieved from the core file.
+ − 129 </td>
+ − 130 </tr>
+ − 131
+ − 132 <tr>
+ − 133 <tr>
+ − 134 <td>
+ − 135 jstackproc.sh,
+ − 136 jstackproc64.sh,
+ − 137 jstackwindbg.bat
+ − 138 jstackwindbg64.bat
+ − 139 </td>
+ − 140 <td>
+ − 141 used to get java stack trace for all java threads.
+ − 142 </td>
+ − 143 </tr>
+ − 144
+ − 145 <tr>
+ − 146 <td>
+ − 147 jhistoproc.sh,
+ − 148 jhistoproc64.sh,
+ − 149 jhistowindbg.bat
+ − 150 jhistowindbg64.bat
+ − 151 </td>
+ − 152 <td>
+ − 153 used to get object histogram of java heap.
+ − 154 </td>
+ − 155 </tr>
+ − 156
+ − 157 <tr>
+ − 158 <td>
+ − 159 permstatproc.sh,
+ − 160 permstatproc64.sh,
+ − 161 permstatwindbg.bat
+ − 162 permstatwindbg64.bat
+ − 163 </td>
+ − 164 <td>
+ − 165 To gather statistics on perm. generation.
+ − 166 </td>
+ − 167 </tr>
+ − 168
+ − 169 <a name="mixed_pstack"></a>
+ − 170 <tr>
+ − 171 <tr>
+ − 172 <td>
+ − 173 pstackproc.sh,
+ − 174 pstackproc64.sh,
+ − 175 pstackwindbg.bat
+ − 176 pstackwindbg64.bat
+ − 177 </td>
+ − 178 <td>
+ − 179 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.
+ − 180 </td>
+ − 181 </tr>
+ − 182
+ − 183 <tr>
+ − 184 <td>
+ − 185 pmapproc.sh,
+ − 186 pmapproc64.sh,
+ − 187 pmapwindbg.bat
+ − 188 pmapwindbg64.bat
+ − 189 </td>
+ − 190 <td>
+ − 191 This is cross platform Solaris pmap-like utility.
+ − 192 </td>
+ − 193 </tr>
+ − 194
+ − 195 <tr>
+ − 196 <td>
+ − 197 soqlproc.sh,
+ − 198 soqlproc64.sh,
+ − 199 soqlwindbg.bat
+ − 200 soqlwindbg64.bat
+ − 201 </td>
+ − 202 <td>
+ − 203 This is command line SOQL - Simple Object Query Language tool.
+ − 204 SOQL is SQL-like query language to query Java heap.
+ − 205 </td>
+ − 206 <tr>
+ − 207 <td>
+ − 208 start-debug-server-proc.sh,
+ − 209 start-debug-server-proc64.sh,
+ − 210 start-debug-server-windbg.bat,
+ − 211 start-debug-server-windbg64.bat,
+ − 212 start-rmiregistry.bat,
+ − 213 start-rmiregistry64.bat,
+ − 214 start-rmiregistry.sh
+ − 215 start-rmiregistry64.sh
+ − 216 </td>
+ − 217 <td>
+ − 218 These scripts are used to run SA remotely.
+ − 219 </td>
+ − 220 </tr>
+ − 221 </table>
+ − 222
+ − 223 <h3>Debugging transported core dumps</h3>
+ − 224 <p>
+ − 225 When a core dump is moved from the machine where it was produced to a
+ − 226 difference machine, it may not always be possible for SA to debug the same.
+ − 227 More info. on debugging on transported core dumps is in
+ − 228 <a href="transported_core.html">transported_core.html</a>.
+ − 229 </p>
+ − 230
+ − 231 <h3>SA Bugs</h3>
+ − 232 <p>
+ − 233 Not all of the possible states of target VMs have been tested (or
+ − 234 supportable) with SA. For example, the SA will probably not work at all
+ − 235 if it freezes the target VM during certain phases of GC. When filing bugs
+ − 236 a pointer to a core file (see gcore(1)) which the SA can not handle well
+ − 237 is best.
+ − 238 </p>
+ − 239
+ − 240 </body>
+ − 241 </html>