Diagnostic tools and data
The J9 virtual machine (VM) produces various types of diagnostic information for analysis. A range of tools can be used to post-process this information and help with problem determination.
Some diagnostic information is targeted towards specific areas of the Java™ runtime environment. For example, a Heap dump provides useful information about class and object instances in the Java heap, whereas J9 tracing is targeted towards more general VM problems.
During problem determination, one of the first objectives is to identify the most probable area
where the problem originates. Many problems that seem to be a Java problem originate elsewhere. Areas where problems can arise include:
- The Java virtual machine (VM)
- Native code
- Java applications
- An operating system or system resource
- A subsystem, such as database code
- Hardware
You might need different tools and different diagnostic information to solve problems in each area. The tools described here are those that are built in to the J9 VM or available to use with the J9 VM. The majority of these tools are cross-platform tools. Many other tools are supplied by hardware or system software vendors, such as system debuggers.
Summary of diagnostic information
A running J9 VM includes mechanisms for producing different types of diagnostic data when different events occur. In general, the production of this data happens under default conditions, but can be controlled by starting the VM with specific options (such as -Xdump). Older versions of the VM controlled the production of diagnostic information through the use of environment variables. You can still use these environment variables, but they are not the preferred mechanism.
The format of diagnostic information produced is specific to the J9 VM and might change between releases.
The following types of diagnostic information can be produced:
- Java dump file
- The Java dump file is sometimes referred to as a Javacore, or thread dump in some VMs. This dump file is in a human-readable format produced by default when the VM ends unexpectedly because of an operating system signal, an OutOfMemoryError exception, or a reserved key combination entered by a user. For example, Ctrl-Break on Windows produces a Java dump file. You can also generate a Java dump file by calling a method from the Dump API, for example com.ibm.jvm.Dump.JavaDump(), from inside the application. A Java dump file summarizes the state of the VM at the instant the signal occurred. Much of the content of the Java dump file is specific to the J9 virtual machine. See Java dump for details.
- Heap dump file
- The VM can generate a heap dump file at the request of the user, by calling com.ibm.jvm.Dump.HeapDump() from inside the application, or by default, when the VM ends because of an OutOfMemoryError exception. You can specify finer control of the timing of the creation of a heap dump file with the -Xdump:heap option. For example, you could request a heap dump file after a certain number of full garbage collections have occurred. The default Heapdump format (phd files) is not human-readable and must be processed by using available tools such as Memory Analyzer. See Using Heapdump for more details.
- System dump file
- System dump files are platform-specific files that contain information about the active processes, threads, and system memory. These files are also known as core dumps on Linux® platforms. System dump files are usually large. By default, system dump files are produced by the VM only when the VM fails unexpectedly because of a GPF (general protection fault) or a major VM or system error. You can also request a system dump file by using the Dump API. For example, you can call the com.ibm.jvm.Dump.SystemDump() method from your application. You can use the -Xdump:system option to produce system dump files when other events occur.
- JIT dump file
- When a general protection fault (GPF) or abort event occurs, the Just-In-Time (JIT) compiler produces a small binary dump file of diagnostic data that can help troubleshoot problems. For more information about the location of this file, see File location.
- Garbage collection data
- A VM started with the -verbose:gc option produces output in XML format that can be used to analyze problems in the Garbage Collector itself or problems in the design of user applications. Numerous other options affect the nature and amount of Garbage Collector diagnostic information produced. For more information, see Garbage Collector diagnostic data.
- Trace data
- J9 tracing allows execution points in the Java code and the internal VM code to be logged. The -Xtrace option allows the number and areas of trace points to be controlled, as well as the size and nature of the trace buffers maintained. The internal trace buffers at a time of failure are also available in a system dump file, and tools are available to extract them from the file. Generally, trace data is written to a file in an encoded format and then a trace formatter converts the data into a readable format. However, if small amounts of trace are to be produced and performance is not an issue, trace can be routed to STDERR and will be pre-formatted. For more information, see Tracing Java applications.
- Other data
- Special options are available for producing diagnostic information relating to the following J9 components:
- The JIT (see Diagnosing a JIT or AOT problem)
- Class loading (see Diagnosing class-loading issues)
- Shared classes (see Diagnosing problems with class data sharing in the OpenJ9 user documentation)
Summary of cross-platform tooling
The following cross-platform tools can be used to help diagnose problems:
- IBM® Monitoring and Diagnostic Tools
- The IBM Monitoring and Diagnostic Tools are a set of GUI-based tools for monitoring applications and analyzing diagnostic data. These tools are designed to make diagnostic tasks as quick and as easy as possible. For more information about the tools, see the IBM Monitoring and Diagnostic tools documentation.
- Cross-platform dump viewer
- The cross-system dump viewer, jdmpview, uses the dump files that the operating system generates to resolve data relevant to the J9 VM. The dump viewer understands the VM and can be used to analyze its internals. It is a useful tool to debug unexpected terminations of the VM. Because the dump viewer is cross-platform, you can analyze a dump from any system, and without knowledge of the system debugger. For more information, see Dump viewer.
- JVMTI tools
- The JVM Tool Interface (JVMTI) is a programming interface for use by tools, replacing the Java Virtual Machine Profiler Interface (JVMPI) and the Java Virtual Machine Debug Interface (JVMDI). For information on the JVMTI, see Java Virtual Machine Tool Interface.
- JPDA tools
- The Java Platform Debugging Architecture (JPDA) is a common standard for debugging a Java VM. J9 is fully JPDA compatible. Any JPDA debugger can be attached to the J9 VM. Because they are debuggers, JPDA tools are best suited to tracing application problems that have repeatable conditions, such as memory leaks in applications, or hangs. An example of a JPDA tool is the debugger that is bundled with Eclipse for Java.
- DTFJ
- The Diagnostic Tool Framework for Java (DTFJ) is a Java application programming interface (API) that is used to support the building of Java diagnostics tools. DTFJ can examine a system dump file to analyze the internal structure of the Java virtual machine. DTFJ is implemented in pure Java code, and tools written by using DTFJ can be cross-platform. Therefore, it is possible to analyze a dump file taken from one machine on another, remote and more convenient, machine. For example, a dump file produced on a z/OS® machine can be analyzed on a Windows Thinkpad. For more information, see Using the Diagnostic Tool Framework for Java.
- Trace formatting
- Trace is a key diagnostic tool. The J9 VM incorporates a large degree of flexibility in determining what is traced and when it is traced. This flexibility enables you to tailor trace so that it has a relatively small effect on performance. The J9 VM also contains many embedded trace points. In this release, maximal tracing is enabled by default for a few level 1 tracepoints and exception trace points. Command-line options allow you to set exactly what is to be traced, and specify where the trace output is to go. Trace output is generally in an encoded format and requires a trace formatter to be viewed successfully.