Using the dump viewer

System dumps are produced in a platform-specific binary format, typically as a raw memory image of the process that was running at the time the dump was initiated. The SDK dump viewer allows you to navigate around the dump, and obtain information in a readable form, with symbolic (source code) data where possible.

You can view Java™ information (for example, threads and objects on the heap) and native information (for example, native stacks, libraries, and raw memory locations).

Dump extractor: jextract

To use the dump viewer you must first use the jextract tool on the system dump. The jextract tool obtains platform specific information such as word size, endianness, data structure layouts, and symbolic information. It puts this information into an XML file. jextract also collects other useful files, depending on the platform, including trace files and copies of executable files and libraries and, by default, compresses these into a single .zip file for use in subsequent problem diagnosis.

The jextract tool must be run in the same mode (-Xgcpolicy:metronome or not) and the same JVM level (ideally the same machine) that was being used when the dump was produced. The combination of the dump file and the XML file produced by jextract allows the dump viewer (jdmpview) to analyze and display Java information.

The extent to which jextract can analyze the information in a dump is affected by the state of the JVM when it was taken. For example, the dump could have been taken while the JVM was in an inconsistent state. The exclusive and prepwalk dump options ensure that the JVM (and the Java heap) is in a safe state before taking a system dump:
-Xdump:system:defaults:request=exclusive+prepwalk
Setting this option adds a significant performance reduction when taking a system dump; which could cause problems in rare situations. This option is not enabled by default.

jextract is in the directory sdk/jre/bin.

To use jextract, enter the following at a command prompt:

jextract -Xgcpolicy:metronome <core_file> [<zip_file>]

or

jextract -Xgcpolicy:metronome -nozip <core_file> [<xml_file>]

The jextract tool accepts these parameters:

-help
Provides usage information.
-nozip
Do not compress the output data.

By default, output is written to a file called <core_file>.zip in the current directory. This file is a compressed file that contains:

You can use the jdmpview tool to analyze the extracted dump locally.

If you run jextract on a JVM level that is different from the one for which the dump was produced you will see the following messages:

J9RAS.buildID is incorrect (found e8801ed67d21c6be, expecting eb4173107d21c673).
This version of jextract is incompatible with this dump.
Failure detected during jextract, see previous message(s).

The contents of the .zip file produced and the contents of the XML are subject to change, you are advised not to design tools based on the contents of these.

Dump viewer: jdmpview

The dump viewer is a tool that allows you to examine the contents of system dumps produced from the JVM. The dump viewer requires metadata created by the jextract tool. It allows you to view both Java and native information from the time the dump was produced.

jdmpview is in the directory sdk/bin.

To start jdmpview, from a shell prompt, enter:

jdmpview -Xgcpolicy:metronome -zip <zip file>

or

jdmpview -Xgcpolicy:metronome -core <core file> [-xml <xml file>]

The jdmpview-Xgcpolicy:metronome tool accepts these parameters:

-core <core file>
Specify a dump file.
-xml <xml file>
Specify a metadata file. jdmpview will guess the name of the XML file if the -xml option is not present.
-zip <zip file>
Specify a .zip file containing the core file and associated XML file (produced by jextract).
Note: The -core and -xml options can be used with the -zip option to specify the core and XML files in the compressed file. Without the -core or -xml options, jdmpview will guess the names of the files in the compressed file.
After jdmpview -Xgcpolicy:metronome processes the arguments with which it was launched, it displays this message:
For a list of commands, type "help"; for how to use "help", type "help help"
> 
When you see this message, you can start using commands.

When jdmpview is used with the -zip option, temporary disk space is needed to uncompress the dump files from the compressed file. jdmpview will use the system temporary directory, /tmp on Linux®. An alternative temporary directory can be specified using the Java system property java.io.tmpdir. jdmpview will display an error message if insufficient disk space is available in the temporary directory.

You can significantly improve the performance of jdmpview against large dumps by ensuring that your system has enough memory available to avoid paging. On large dumps (that is, ones with large numbers of objects on the heap), you might have to run jdmpview using the -Xmx option to increase the maximum heap available:
jdmpview -Xgcpolicy:metronome -J-Xmx<n> -zip <zip file>
To pass command-line arguments to the JVM, you must prefix them with -J.


© Copyright IBM Corporation 2005, 2010. All Rights Reserved.
© Copyright Sun Microsystems, Inc. 1997, 2007, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information center is powered by Eclipse technology. (http://www.eclipse.org/)