Troubleshooting Guide for Java SE 6 with HotSpot VM

• Document Information
• Preface
• 1.Diagnostic Tools and Options
• 2.Detailed Tool Descriptions
• 3.Troubleshooting Memory Leaks
• 4.Troubleshooting System Crashes
• 5.Troubleshooting Hanging or Looping Processes
• 6.Integrating Signal and Exception Handling
• 7.Submitting Bug Reports
• A.Environment Variables and System Properties
• B.Command-Line Options
• C.Fatal Error Log
• D.Summary of Tools in This Release
• D.1 Troubleshooting Tools Available in Java SE 6
• D.1.1 Solaris OS and Linux
• D.1.2 Windows Operating System
• D.2 Changes to Troubleshooting Tools in Java SE 6

Appendix D

Summary of Tools in This Release

This appendix presents a summary of tools available in the current release of Java SE, as well as the changes since the previous release.

D.1 Troubleshooting Tools Available in Java SE 6

This section lists the troubleshooting tools available by platform: Unix (Solaris OS and Linux) and Windows.

D.1.1 Solaris OS and Linux

All the JDK troubleshooting tools that are described in this document are available in Java SE 6 on both Solaris OS and Linux.

D.1.2 Windows Operating System

The following JDK troubleshooting tools are also available in Java SE 6 on the Windows operating system.

• HPROF profiler
• JConsole utility
• jdb utility
• jhat utility
• jinfo utility - only the option jinfo -flag pid
• jmap utility - only the following options:

  • jmap -dump:format=b,file= file pid

  • jmap -histo[:live] pid

• jps utility (not currently available on Windows 98 or Windows ME)
• jrunscript utility
• jstack utility - only the option jstack [-l] pid
• jstat utility (not currently available on Windows 98 or Windows ME)
• jstatd daemon (not currently available on Windows 98 or Windows ME)
• visualgc tool (not currently available on Windows 98 or Windows ME)

D.2 Changes to Troubleshooting Tools in Java SE 6

This is a list of changes to the JDK troubleshooting tools and options from J2SE 1.5 to Java SE 6.

• The Java VisualVM tool is included in Java SE releases starting with release 6 update 7.
• The Heap Analysis Tool (HAT) has been replaced by the new jhat command–line tool. This new tool has the same functionality as HAT, with the following additional enhancements:

  • jhat can parse incomplete and truncated heap dumps.

  • jhat can read heap dumps generated on 64–bit systems.

  • jhat supports Object Query Language (OQL), with which you can create your own queries on the heap dump.

  For information about HAT, see Java 2 Platform, Standard Edition 5.0, Troubleshooting and Diagnostic Guide, which is located here.

• The JConsole tool has the following changes.

  • A new user interface (button) is provided for deadlock detection, including java.util.concurrent locks.

  • The Connection dialog is new.

  • The Overview tab is new.

  • You no longer need to specify the -Dcom.sun.management.jmxremote command-line option when starting the application to be monitored.

  • You can connect to a VM using the attach mechanism.

  • You can pass a flag on the command line to the VM that is running JConsole.

  • The com.sun.management.HotSpotDiagnostic MBean property is new. In the MBean tab, you can use this property to dump heap, get and set VM options, and change management options dynamically.

• The jdb tool has the following changes:

  • Shows return values in method and exit traces.

  • Trace method entry/exit without stopping.

  • The JPDA ProcessAttachingConnector is new.

• The jinfo tool has the following changes:

  • The new jinfo -flag option allows you to dynamically set, unset, and change the values of certain Java VM flags for a specified Java process.

  • The jinfo command is new to Windows, but only the option jinfo -flag pid.

• The jmap command has the following changes:

  • The jmap -finalizerinfo option is new. With this option, the command prints information on objects awaiting finalization.

  • The jmap -permstat option has been updated to print also the number and size of internalized String instances.

  • The jmap -dump:format=b,file= filename option is new. With this option, jmap obtains a heap dump from a running process or from a core file and writes it in binary HPROF format to a specified file. This file can then be analyzed with the jhat tool.

  • The jmap -F option is new and is for Solaris OS and Linux only. This option forces the use of the Serviceability Agent in case the process does not respond.

  • The jmap -J option is new and is for Solaris OS and Linux only. This option passes flags to the VM on which jmap is running.

  • The live suboption is new for the histo option. With this suboption only live objects are counted.

  • The jmap command is new to Windows, but only the jmap -dump: dump-options pid option and the jmap -histo[:live] pid option.

• The jrunscript tool is new.
• The jstack command has the following changes:

  • The jstack pid option has been changed to work like remote Ctrl-Break, that is, the output of the thread dump is slightly different, and there is more information on deadlocks and JNI Global References.

  • The jstack -F option is new and is for Solaris OS and Linux only. This option forces a thread dump in case the VM is hung.

  • The jstack -l option is new. This option prints information about ownable synchronizers (locks) in the heap.

  • The jstack command is new to Windows, but only the jstack pid option and the jstack -l pid option.

• The -XX:OnOutOfMemoryError= string option allows you to specify a command or script to be run when an OutOfMemoryError is first thrown. This is useful for data capture, for example, with jmap.
• The -XX:+HeapDumpOnOutOfMemoryError command-line option is new as of Java SE release 5 update 7. If this option is set and the VM detects a native out–of–memory error, a heap dump is generated. See B.1.2 -XX:+HeapDumpOnOutOfMemoryError Option .
• Other new environment variables to help in troubleshooting out-of-memory errors are the following:

  • -XX:HeapDumpPath= pathname

  • -XX:SegmentedHeapDumpThreshold= threshold

  • -XX:HeapDumpSegmentSize= size

• The fatal error log has the following changes:

  • You now have the ability to specify a location for the fatal error log. See C.1 Location of Fatal Error Log.

  • There is now a URL at the beginning of fatal error log for reporting incidents. See C.3 Header Format.

• The VM now contains two built-in DTrace probe providers: hotspot and hotspot_jni. (Solaris 10 OS only)
• The fastdebug builds can be useful for testing, diagnosing, and isolating problems. However, they should not be used in production environments.
• The Ctrl-Break handler has the following changes:

  • Ctrl-Break now shows the thread state.

  • Ctrl-Break now shows the sizes of the heap areas.

  • With -XX:+PrintConcurrentLocks, Ctrl-Break will also print the list of concurrent locks owned by each thread, as well as detect deadlocks involving both monitor locks and concurrent locks.

• The HPROF format=b option now includes primitive type instance fields and primitive array content in heap dumps.
• When the java.lang.OutOfMemoryError error is thrown, a stack trace is now printed also. In addition, when the specific message indicates that the system is almost out of swap space ( Out of swap space?), a fatal error log is now generated.