Java Platform, Standard Edition Troubleshooting Guide
Contents Previous Next

17.3 Collect Data for a Bug Report

In general, it is recommended to test with the available latest update release or even an available latest EA (Early Access) release to see if the issue persists and then collect as much relevant data as possible when you create a bug report or submit a support call. The following sections suggest the data to collect and, where applicable, it provides recommendations for the commands or general procedure for obtaining the data.

Detailed Description of the Problem
Hardware Details
Operating System Details
Java SE Version
Command-Line Options
Environment Variables
Fatal Error Log
Core or Crash Dump
Logs and Traces

17.3.1 Detailed Description of the Problem

When creating a problem description, try to include as much relevant information as possible.

Describe the application, the environment, and the most important events leading up to the time when the problem happened.

Report all troubleshooting steps and results that have already occurred.

Sometimes, the problem can be reproduced only in a complex application environment. In this case, the description, coupled with logs, core file, and other relevant information, might be the only way to diagnose the issue. In these situations, the description should indicate if the submitter is willing to run further diagnostics or run test binaries on the system where the issue occurs.

If the problem is reproducible at will, then list the steps that are required to demonstrate the problem.
If the problem can be demonstrated with a small test case, then include the test case and the commands to compile and execute the test case.
If the test case or problem requires third-party code, such as a commercial or open source library or package, then provide then details about where and how to obtain the library.

17.3.2 Hardware Details

Sometimes a bug arises or can be reproduced only on certain hardware configurations. If a fatal error occurs, the error log might contain the hardware details. If an error log is not available, document in the bug report the number and the type of processors in the machine, the clock speed, and, where applicable and if known, some details on the features of that processor. For example, in the case of Intel processors, it might be relevant that hyper-threading is available.

17.3.3 Operating System Details

On the Oracle Solaris operating system, the showrev -a command prints the operating system version and patch information.

On Linux, it is important to know which distribution and version is used. Sometimes the /etc/*release file indicates the release information, but as components and packages can be upgraded independently, it is not always a reliable indication of the configuration. Therefore, in addition to the information from the *release file, collect the following information:

The kernel version. This can be obtained using the uname -a command.
The glibc version. The rpm -q glibc command indicates the patch level of glibc.
The thread library. There are two thread libraries for Linux, namely LinuxThreads and NPTL. The LinuxThreads library is used on 2.4 and older kernels and has "fixed stack" and "floating stack" variants. The Native POSIX Thread Library (NPTL) is used on the 2.6 kernel. Some Linux releases (such as RHEL3) include backports of NPTL to the 2.4 kernel. Use the command getconf GNU_LIBPTHREAD_VERSION to determine which thread library is used. If the getconf command returns an error to say that the variable does not exist, then it is likely that you are using an old kernel with the LinuxThreads library.

17.3.4 Java SE Version

The Java SE version string can be obtained using the java -version command.

Multiple versions of Java SE may be installed on the same machine. Therefore, ensure that you use the appropriate version of the java command by verifying that the installation bin directory appears in your PATH environment variable before other installations.

17.3.5 Command-Line Options

If the bug report does not include a fatal error log, it is important to document the full command line and all its options. This includes any options that specify heap settings (for example, the -Xmx option) or any -XX options that specify HotSpot specific options.

If you can reproduce the issue at will, and you're able to read standard output (stdout) for the JVM, then you can add the -XX:+PrintCommandLineFlags option to obtain the full list of command-line options used by the application. This option will be active the next time the JVM is restarted.

You can also run the jcmd (Windows)/jcmd (Oracle Solaris and Linux) command as follows to obtain the command-line options of a running VM:

jcmd <process ID for the Java process> VM.command_line

In addition, you can change the flags of a running JVM through jcmd. See the VM.set_flag command.

17.3.6 Environment Variables

Sometimes problems arise due to environment variable settings. When creating the bug report, indicate the values of the following Java environment variables (if set).

JAVA_TOOL_OPTIONS
_JAVA_OPTIONS
CLASSPATH
JAVA_COMPILER
PATH
USERNAME

Note:

You should obtain the values of environment variables from the context of the failing application. In addition, one or more configuration files may set the values of these environment variables for that failing application.

In addition, collect the following operating-system-specific environment variables.

On Oracle Solaris and Linux operating systems, collect the values of the following environment variables:
- LD_LIBRARY_PATH
- LD_PRELOAD
On Windows, collect the values of the following environment variables:
- OS
- PROCESSOR_IDENTIFIER
- _ALT_JAVA_HOME_DIR

17.3.7 Fatal Error Log

When a fatal error occurs, an error log is created. For detailed information about this file, see Appendix A: Fatal Error Log.

The error log contains much information obtained at the time of the fatal error, such as version and environment information, details on the threads that provoked the crash, and so forth.

If the fatal error log is generated, be sure to include it in the bug report or support call.

17.3.8 Core or Crash Dump

If a core file or crash dump has been created because of the reported issue, include it with the bug, size permitting.

A Linux core file or a Windows crash dump contains the memory state of either an application or the operating system at the time the core or dump was created. Depending on a system's configuration, a core or crash dump may be created automatically when a crash happens. Consult with the system administrator to determine if a core file will be generate automatically and where.

In the case of a hung process, the procedure for generating a dump is described in Collect Core Dumps.

17.3.9 Logs and Traces

In some cases, log or trace output can help to quickly determine the cause of a problem.

For example, in the case of a performance issue the output of the -verbose:gc option can help in diagnosing the problem. This option enables output from the garbage collector.

In other cases, you can use Java Flight Recorder (see What Are Java Flight Recordings) and JDK Mission Control to capture statistical information over the time period leading up to the problem.

Note:

Java Flight Recorder (JFR) is a commercial feature. You can use it for free on developer computers and for evaluation purposes in test, development, and production environments. However, to enable JFR on a production server, you need a commercial license. Using the JDK Mission Control user interface for other purposes on the JDK, such as producing a flight recording for purely diagnostic purposes, does not require a commercial license. For more details about JFR commercial features and availability, see Oracle Java SE Universal Subscription.

In the case of a deadlock or a hung VM, the thread stacks can help diagnose the problem. Obtain thread stacks by pressing Control+\ on Oracle Solaris and Linux or Control+Break on Windows. Alternatively, use the Thread.dump_to_file option in the jcmd (Windows)/jcmd (Oracle Solaris and Linux) command.

In general, provide all relevant logs, traces, and other output in the bug report or during the support call.

Contents Previous Next