Module openj9.jvm
Package com.ibm.jvm

Class Dump

java.lang.Object
com.ibm.jvm.Dump
public class Dump extends Object
This class is used to trigger and configure the options used to produce different types of diagnostic dumps available from the OpenJ9 JVM.

-Xdump must be enabled on the command line or the functions that attempt to cause dumps to be created or set options will fail with a java.lang.RuntimeException.

The methods on this class can be used to trigger dumps, configure dump options and query those options.

The JavaDump(), SystemDump(), HeapDump() and SnapDump() methods trigger dumps of the given type with no options and no return value. Although they are not configurable they do provide an easy API to use via reflection if your code is likely to run on both OpenJ9 and non-OpenJ9 JVMs and you only need the most basic ability to create a dump.

The javaDumpToFile(), systemDumpToFile(), heapDumpToFile() and snapDumpToFile() methods allow a destination file to be optionally specified and will return the full path of the file that is created.
The recommended usage of the javaDumpToFile(), systemDumpToFile(), heapDumpToFile() and snapDumpToFile() methods is to call the no argument versions of these calls rather than specifying a file name as this will trigger a dump to the default location. Your dump file will go to the default location specified by any -Xdump options given to the JVM at startup time following the user or administrators preferences. The location the dump file was written to will be returned as a String so the generated file can be located.

The triggerDump(String) method offers similar functionality as the DumpToFile() methods but with the ability to specify any dump options that are meaningful for a dump that occurs immediately. The options are passed as a String that follows the same format as the option strings passed to -Xdump on the command line.
For example:

  • triggerDump("java") is equivalent to javaDumpToFile() or javaDumpToFile(null) all three will cause a javadump to be generated to the default location.
  • triggerDump("heap:file=heapdump.phd") is equivalent to heapDumpToFile("heapdump.phd")
  • triggerDump("heap:file=heapdump.txt,opts=CLASSIC") allows you to specify the CLASSIC option to triggerDump and produce a text format heap dump which is not possible through the *DumpToFile(String filename) or *Dump() methods.
  • triggerDump("java:request=exclusive") will trigger a java dump with the request option set to "exclusive" and any other options, including the file name, taken from the default options for java dumps

The setDumpOptions(String) method allows dump options that will cause or change how a dump occurs for an event in the future to be specified. The options are specified in the format expected by the -Xdump command line. Not all options can be configured at runtime and this method will throw an InvalidDumpOption exception if it is passed an option that cannot be set.

For example:

  • setDumpOptions("java") - enable java dumps with the default settings.
  • setDumpOptions("java:events=vmstop") - enable java dumps on the vmstop event (this will occur once when the JVM exits).
  • setDumpOptions("none") - disable all dump agents on all events.
  • setDumpOptions("heap:none") - disable all heap dump agents on all events.
  • setDumpOptions("system:none:events=systhrow,filter=java/lang/OutOfMemoryError") - disable system dumps on systhrow events for OutOfMemory errors only.
For full details of dump options see the section on dump agents in the documentation for the OpenJ9 JVM.

The queryDumpOptions() method returns a String array containing a snapshot of the currently configured dump options. Each String is in the format expected by the -Xdump command line option and setDumpOptions. The Strings can be passed back to setDumpOptions to recreate the current dump agent configuration at a later time.

The resetDumpOptions() method resets the dump options to the settings specified when the JVM was started removing any additional configuration done since then.
If you wish to change the dump configuration at runtime and then reset it to an earlier state that included additional runtime configuration done through this API or JVMTI you should consider saving the result of queryDumpOptions and then later use setDumpOptions(String) to restore that configuration after a call to setDumpOptions("none") to clear all dump agent configuration.