This appendix describes some command-line options that can be useful in diagnosing problems with the Java HotSpot VM.
This appendix contains the following sections:
Command-line options that are prefixed with
-XX are specific to the Java HotSpot Virtual Machine. Many of these options are important for performance tuning and diagnostic purposes, and are therefore described in this appendix. For information on all possible
-XX options, see the Java HotSpot VM Options web page at
You can dynamically set, unset, or change the value of certain Java VM flags for a specified Java process using the
jinfo -flag command (see "The
jinfo Utility") and the JConsole utility (see "JConsole").
For a complete list of these flags, use the MBeans tab of the JConsole utility. See the list of values for the
DiagnosticOptions attribute of the
HotSpotDiagnostic MBean, which is in the
com.sun.management domain. These flags are the following:
This option tells the HotSpot VM to generate a heap dump when an allocation from the Java heap or the permanent generation cannot be satisfied. There is no overhead in running with this option, so it can be useful for production systems where the
OutOfMemoryError exception takes a long time to surface.
You can also specify this option at runtime with the MBeans tab in the JConsole utility.
The heap dump is in HPROF binary format, and so it can be analyzed using any tools that can import this format. For example, the
jhat tool can be used to do rudimentary analysis of the dump. For more information on the
jhat tool, see "The
The following example shows the result of running out of memory with this flag set:
java -XX:+HeapDumpOnOutOfMemoryError -mn256m -mx512m ConsumeHeapjava.lang.OutOfMemoryError: Java heap space Dumping heap to java_pid2262.hprof ... Heap dump file created [531535128 bytes in 14.691 secs] Exception in thread "main" java.lang.OutOfMemoryError: Java heap space at ConsumeHeap$BigObject.(ConsumeHeap.java:22) at ConsumeHeap.main(ConsumeHeap.java:32)
ConsumeHeap fills up the Java heap and runs out of memory. When the
java.lang.OutOfMemoryError exception is thrown, a heap dump file is created. In this case the file is 507 MB and is created with the name java_pid2262.hprof in the current directory.
By default the heap dump is created in a file called java_pidpid.hprof in the working directory of the VM, as in the example above. You can specify an alternative file name or directory with the
-XX:HeapDumpPath= option. For example
-XX:HeapDumpPath=/disk2/dumps will cause the heap dump to be generated in the /disk2/dumps directory.
When a fatal error occurs, the HotSpot VM can optionally execute a user-supplied script or command. The script or command is specified using the
-XX:OnError=string command-line option, where string is a single command, or a list of commands separated by semicolons. Within this string, all occurrences of
%p are replaced with the current PID, and all occurrences of
%% are replaced by a single
%. The following examples demonstrate how this option can be used when launching a Java application named MyApp with the
On Solaris OS the
pmap command displays information about the address space of a process. In the example above, if a fatal error occurs, the
pmap command is executed to display the address space of the current process.
In the example above, the contents of the fatal error log file are mailed to a support alias when a fatal error is encountered.
On Solaris OS the
gcore command creates a core image of the specified process, and the
dbx command launches the debugger. In the example above, the
gcore command is executed to create the core image of the current process, and the debugger is started to attach to the process when an unexpected error is encountered.
On Linux the
gdb command launches the debugger. In the example above, the
gdb debugger is launched and attached to the current process when an unexpected error is encountered.
On Windows the
userdump.exe utility creates a crash dump of the specified process. The utility does not ship with Windows and should be downloaded from the Microsoft website as a part of the Microsoft OEM Support Tools package.
In the above example, the
userdump.exe utility is executed to create a core dump of the current process in case of a fatal error.
The example assumes that the path to the
If you do not have the
For more information on creating crash dumps on Windows, see "Collecting Crash Dumps on Windows".
When this option is set and a fatal error is encountered, the HotSpot VM will display information about the fatal error and prompt the user to specify whether the native debugger is to be launched. In the case of Solaris OS and Linux, the output and prompt are sent to the application console (standard input and standard output). In the case of Windows, a Windows message box pops up.
The following is an example of a fatal error encountered on a Linux system:
============================================================================== Unexpected Error ------------------------------------------------------------------------------ SIGSEGV (0xb) at pc=0x2000000001164db1, pid=10791, tid=1026 Do you want to debug the problem? To debug, run 'gdb /proc/10791/exe 10791'; then switch to thread 1026 Enter 'yes' to launch gdb automatically (PATH must include gdb) Otherwise, press RETURN to abort... ==============================================================================
In this case a
SIGSEGV error has occurred and the user is prompted to specify whether the
gdb debugger is to be launched to attach to the process. If the user enters
gdb will be launched (assuming it is set in the
On Solaris OS the message is similar to the above except that the user is prompted to start the
On Windows a message box is displayed. If the user clicks Yes, the VM will attempt to start the default debugger. This debugger is configured by a registry setting which is described in "Collecting Crash Dumps on Windows". If Microsoft Visual Studio is installed, the default debugger is typically configured to be
In the above example the output includes the PID (
pid=10791) and also the thread ID (
tid=1026). If the debugger is launched, one of the initial steps in the debugger might be to select the thread and obtain its stack trace.
As the process is waiting for a response it is possible to use other tools to obtain a crash dump or query the state of the process. On Solaris OS, for example, a core dump can be obtained using the
On Windows a Dr. Watson crash dump can be obtained using the
windbg programs. The
windbg utility is included in Microsoft's Debugging Tools for Windows and is described in "Collecting Crash Dumps on Windows". In
windbg, select the Attach to a Process menu option, which displays the list of processes and prompts for the PID. The HotSpot VM displays a message box, which includes the PID. Once selected the
.dump /f command can be used to force a crash dump. In the following example a crash dump is created in a file named crash.dump.
Figure B-1 Example of a Crash Dump Created by windbg
In general the
-XX:+ShowMessageBoxOnError option is more useful in a development environment where debugger tools are available. The
-XX:OnError option is more suitable for production environments where a fixed sequence of commands or scripts are executed when a fatal error is encountered.
-XX command-line options can be useful in troubleshooting:
This option can be used to specify a command or script to execute when an
OutOfMemoryError exception is thrown.
This option can be used to specify a location for the fatal error log file (see "Location of Fatal Error Log").
This option can be used to specify a location for the heap dump (see "The
This option can be used to specify the size of the permanent generation memory (see "Exception in thread thread_name: java.lang.OutOfMemoryError: PermGen space").
This option can be used to print all the VM command-line flags (see "Collecting Data for a Bug Report").
This option can be used to cause the Control+Break handler to print a list of concurrent locks owned by each thread.
This option can be used to cause the Control+Break handler to print a heap histogram.
These options can be used to print detailed information about garbage collection (see "The
On Solaris 8 and 9 OS, this option can be used to instruct the HotSpot VM to use alternate signals to
SIGUSR2 (see "Signal Handling on Solaris OS and Linux").
These options can be used to specify the garbage collection policy to be used (see "Working Around Crashes During Garbage Collection").
In addition to the
-XX options, many other command-line options can provide troubleshooting information. This section describes a few of these options.
This option is useful in diagnosing problems with applications that use the Java Native Interface (JNI). Sometimes bugs in the native code can cause the HotSpot VM to crash or behave incorrectly.
-Xcheck:jni option is added to the command line that starts the application, as in the following example:
java -Xcheck:jni MyApp
-Xcheck:jni option causes the VM to do additional validation on the arguments passed to JNI functions. Note that the option is not guaranteed to find all invalid arguments or diagnose logic bugs in the application code, but it can help diagnose a large number of such problems.
When an invalid argument is detected, the VM prints a message to the application console or to standard output, prints the stack trace of the offending thread, and aborts the VM.
In the following example, a
null value was incorrectly passed to a JNI function that does not allow a
FATAL ERROR in native method: Null object passed to JNI at java.net.PlainSocketImpl.socketAccept(Native Method) at java.net.PlainSocketImpl.accept(PlainSocketImpl.java:343) - locked <0x450b9f70> (a java.net.PlainSocketImpl) at java.net.ServerSocket.implAccept(ServerSocket.java:439) at java.net.ServerSocket.accept(ServerSocket.java:410) at org.apache.tomcat.service.PoolTcpEndpoint.acceptSocket (PoolTcpEndpoint.java:286) at org.apache.tomcat.service.TcpWorkerThread.runIt (PoolTcpEndpoint.java:402) at org.apache.tomcat.util.ThreadPool$ControlRunnable.run (ThreadPool.java:498) at java.lang.Thread.run(Thread.java:536)
In the following example, an incorrect argument was provided to a JNI function that expects a
FATAL ERROR in native method: Instance field not found in JNI get/set field operations at java.net.PlainSocketImpl.socketBind(Native Method) at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:359) - locked <0xf082f290> (a java.net.PlainSocketImpl) at java.net.ServerSocket.bind(ServerSocket.java:318) at java.net.ServerSocket.<init>(ServerSocket.java:185) at jvm003a.<init>(jvm003.java:190) at jvm003a.<init>(jvm003.java:151) at jvm003.run(jvm003.java:51) at jvm003.main(jvm003.java:30)
The following list presents examples of other problems that the
-Xcheck:jni option can help diagnose:
Cases where the JNI environment for the wrong thread is used
Cases where an invalid JNI reference is used
Cases where a reference to a non-array type is provided to a function that requires an array type
Cases where a non-static field ID is provided to a function that expects a static field ID
Cases where a JNI call is made with an exception pending
In general, all errors detected by the
-Xcheck:jni option are fatal errors (that is, the error is printed and the VM is aborted). There is one exception to this behavior, when a JNI call is made within a JNI critical region. In this case, the following non-fatal warning message is printed:
Warning: Calling other JNI functions in the scope of Get/ReleasePrimitiveArrayCritical or Get/ReleaseStringCritical
A JNI critical region is created when native code uses the JNI functions
GetStringCritical to obtain a reference to an array or string in the Java heap. The reference is held until the native code calls the corresponding release function. The code between the get and release is called a JNI critical section and during that time the HotSpot VM cannot bring the VM to a state that allows garbage collection to occur. The general recommendation is not to use other JNI functions within a JNI critical section, and in particular any JNI function that could potentially cause a deadlock. The warning printed above by the
-Xcheck:jni option is thus an indication of a potential issue; it does not always indicate an application bug.
For more information on JNI, refer to the Java Native Interface documentation at
This option enables logging of class loading and unloading.
This option enables logging of garbage collection (GC) information. It can be combined with other HotSpot VM specific options such as
-XX:+PrintGCTimeStamps to get further information about GC. The information output includes the size of the generations before and after each GC, total size of the heap, the size of objects promoted, and the time taken.
These options, together with detailed information about GC analysis and tuning, are described in the GC Portal article at
-verbose:gc option can be dynamically enabled at runtime using the management API or JVM TI. For more information on these APIs, see "Custom Diagnostic Tools".
The JConsole monitoring and management tool can also enable or disable the option when the tool is attached to a management VM. For more information on JConsole, see "JConsole".
This option enables logging of JNI. When a JNI or native method is resolved, the HotSpot VM prints a trace message to the application console (standard output). It also prints a trace message when a native method is registered using the JNI
RegisterNative function. The
-verbose:jni option can be useful in diagnosing issues with applications that use native libraries.