1 Prepare Java for Troubleshooting

This section provides some guidelines for setting up both Java and a Java application for easier troubleshooting. These proactive steps enable the collection of useful data and help define problems arising from an application.

Topics

• Update the Java Runtime
• Enable Options and Flags for JVM Troubleshooting
• Make a Java Application Easier to Debug
• Gather Relevant Data

Update the Java Runtime

Use the latest version of Java SE to avoid spending time on troubleshooting issues in Java SE that were fixed. Often, a problem caused by a bug in the Java runtime is fixed in the latest update release. Working with the latest Java SE version helps avoid some known and common issues.

Note:

Depending on your situation or circumstances, it might not be possible to update or upgrade to the latest Java SE version.

Enable Options and Flags for JVM Troubleshooting

Set up JVM options and flags to enable gathering relevant data for troubleshooting.

The data you gather depends on the operating system and type of problem you are having or expect to have. Consider gathering the following data:

1. Enable core files: If Java crashes, the OS may save a core file to disk. A core file is a complete dump of the application's memory usage. Creation of core files is typically disabled by default. Consult your system administrator or OS documentation for details on how to enable the production of core files.

   For example, on Linux, core files are sometimes disabled by default. To enable core files on Linux, it is usually enough to run the ulimit -c unlimited before starting the application command. Some systems may have different ways to handle these limits.

   Note:

   Core files may take up a lot of disk space depending on the memory usage of the application.

   Core files provide detailed information about the state of an application at the time of a crash. They're not always useful in diagnosing a problem but are invaluable when they are needed. Because crashes are often difficult to reproduce, having application core files enabled can save time and provide valuable information. It's up to your and your organization to decide whether your system can meet the potential space requirements.

2. Add -XX:+HeapDumpOnOutOfMemoryError to the JVM flags: The -XX:+HeapDumpOnOutOfMemoryError flag saves a Java heap dump to disk if the applications runs into an OutOfMemoryError.

   A heap dump provides information on that portion of an application's memory usage that is managed by the JVM directly. Like core files, heap dumps can be very large. A heap dump can identify if part of an application is growing out of proportion to the rest, which may cause an OutOfMemoryError.

3. Run a continuous flight recording: Set up Java to run with a continuous flight recording.

   Continuous flight recordings provide a file-based record of JVM events. This provides a low-overhead means of monitoring a Java application that can be used in the event of an issue. See Produce a Flight Recording for how to setup such recordings.

4. Add the -Xlog:gc* command-line option: The -Xlog:gc option prints detailed information about garbage collection, which helps diagnose problems with application performance and memory management.

   See Enable Logging with the JVM Unified Logging Framework in the java command documentation for more information about this option and other information that the JVM Unified Logging Framework can print.

   Note:

   Creating a discrete garbage collection log file makes it easier to read. It also persists after a crash or application restart. Setting up log rotation enables you to manage the amount of information retained and for how long. See -Xlog Output in the java command documentation for how to do this.

5. Print Java version and JVM flags: Oracle Support, and even forums, ask for the exact Java version your application uses and its JVM flags.

   Run java -version at a command line to obtain the default Java version of your system. If your application starts with a script, read through it and any associated configuration files to find out if your application is using something other than the default Java version. Alternatively, add -XX:PrintFlagsFinal and -showversion to your application's JVM arguments, restart your application, and read the application logs for the results.

6. Set up Java Management Extensions (JMX) for remote monitoring: JMX is a framework for monitoring Java applications. It's typically used through tools like Mission Control or VisualVM. Ensuring that the application is open to remote monitoring helps if you don't have direct access to the application or its system. There is no overhead for opening up JMX to remote access. To do this, add com.sun.management.jmxremote.port=portNum to the application's JVM flags, and then restart your application. See Monitoring and Management Using JMX Technology in Java Platform, Standard Edition Monitoring and Management Guide for details.

Make a Java Application Easier to Debug

Using a logging framework is a good way to enable future debugging.

If you run into problems in a specific module, you should be able to enable logging in that module. It is also good to specify different levels of logging, for example info, debug, and trace. For more information about Java logging, see Java Logging Overview.

Gather Relevant Data

If your application runs into a problem and you want to start the debugging process, collecting data about the issue is the first step. This is especially true as restarting an application or system will move or delete files.

• If your application crashed, then gather these files:
  • Core files
  • Fatal error log file: See Location of Fatal Error Log
  • Java and application logs
  • Java heap dumps from -XX:+HeapDumpOnOutOfMemoryError
  • Flight recordings: If the problem didn't terminate the application, dump the continuous recordings
• If the application stopped responding, then gather these files:
  • Stack traces: Take several stack traces using jcmd <pid> Thread.print before restarting the system
  • Dump flight recordings
  • Forced core file: See your operating system's documentation for how to force a core file