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.

Method Summary

Modifier and Type	Method and Description
static void	HeapDump() Trigger a heap dump.
static String	heapDumpToFile() Trigger a heap dump.
static String	heapDumpToFile(String fileNamePattern) Trigger a heap dump.
static void	JavaDump() Trigger a java dump.
static String	javaDumpToFile() Trigger a java dump.
static String	javaDumpToFile(String fileNamePattern) Trigger a java dump.
static String[]	queryDumpOptions() Returns the current dump configuration as an array of Strings.
static void	resetDumpOptions() Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then.
static void	setDumpOptions(String dumpOptions) Sets options for the dump subsystem.
static void	SnapDump() Trigger a snap dump.
static String	snapDumpToFile() Trigger a snap dump.
static String	snapDumpToFile(String fileNamePattern) Trigger a snap dump.
static void	SystemDump() Trigger a system dump.
static String	systemDumpToFile() Trigger a system dump.
static String	systemDumpToFile(String fileNamePattern) Trigger a system dump.
static String	triggerDump(String dumpOptions) Trigger a dump with the specified options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

JavaDump

public static void JavaDump()

Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission

Throws:

RuntimeException - if the vm does not contain RAS dump support

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

HeapDump

public static void HeapDump()

Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission

Throws:

RuntimeException - if the vm does not contain RAS dump support

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

SystemDump

public static void SystemDump()

Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission

Throws:

RuntimeException - if the vm does not contain RAS dump support

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

SnapDump

public static void SnapDump()

Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the OpenJ9 JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission

Throws:

RuntimeException - if the vm does not contain RAS dump support

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

javaDumpToFile

public static String javaDumpToFile(String fileNamePattern)
                             throws InvalidDumpOptionException

Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the OpenJ9 JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:

• null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
• Replacement (%) tokens were specified in the file name. These will have been expanded.
• The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
• The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.

If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Parameters:

fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens

Returns:

the file name that the dump was actually written to

Throws:

InvalidDumpOptionException - if the filename was invalid

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

javaDumpToFile

public static String javaDumpToFile()

Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Returns:

the file name that the dump was actually written to

Throws:

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

heapDumpToFile

public static String heapDumpToFile(String fileNamePattern)
                             throws InvalidDumpOptionException

Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the OpenJ9 JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:

• null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
• Replacement (%) tokens were specified in the file name. These will have been expanded.
• The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
• The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.

If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Parameters:

fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens

Returns:

the file name that the dump was actually written to

Throws:

InvalidDumpOptionException - if the filename was invalid

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

heapDumpToFile

public static String heapDumpToFile()

Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Returns:

the file name that the dump was actually written to

Throws:

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

systemDumpToFile

public static String systemDumpToFile(String fileNamePattern)
                               throws InvalidDumpOptionException

Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the OpenJ9 JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:

• null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
• Replacement (%) tokens were specified in the file name. These will have been expanded.
• The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
• The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.

If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Parameters:

fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens

Returns:

the file name that the dump was actually written to

Throws:

InvalidDumpOptionException - if the filename was invalid

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

systemDumpToFile

public static String systemDumpToFile()

Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Returns:

the file name that the dump was actually written to

Throws:

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

snapDumpToFile

public static String snapDumpToFile(String fileNamePattern)
                             throws InvalidDumpOptionException

Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the OpenJ9 JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the OpenJ9 JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:

• null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
• Replacement (%) tokens were specified in the file name. These will have been expanded.
• The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
• The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.

If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Parameters:

fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens

Returns:

the file name that the dump was actually written to

Throws:

InvalidDumpOptionException - if the filename was invalid

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

snapDumpToFile

public static String snapDumpToFile()

Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the OpenJ9 JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Returns:

the file name that the dump was actually written to

Throws:

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

triggerDump

public static String triggerDump(String dumpOptions)
                          throws InvalidDumpOptionException

Trigger a dump with the specified options. This method will trigger a dump of the specified type, with the specified options, immediately. The dump type and options are specified using the same string parameters as the -Xdump flag as described in the section on dump agents in the documentation for the OpenJ9 JVM. Settings that do not apply to dumps that occur immediately ("range=", "priority=", "filter=", "events=", "none" and "defaults") will be ignored. The "opts=" setting is supported if an option is used that causes two dumps to occur only the filename for the first will be returned. If a filename is specified for the dump it may contain replacement strings as specified in the documentation. In addition if a dump cannot be created with the specified filename the JVM may attempt to write it to another location. For these reasons you should always use the file name that is returned from this function when looking for the dump rather than the name you supplied. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is requested an additional check for com.ibm.jvm.ToolDumpPermission will also be made.

Parameters:

dumpOptions - a dump settings string

Returns:

The file name of the dump that was created. The String "-" means the dump was written to stderr.

Throws:

RuntimeException - if the vm does not contain RAS dump support

SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump

InvalidDumpOptionException - If the dump options are invalid or the dump operation fails

NullPointerException - if dumpSettings is null

setDumpOptions

public static void setDumpOptions(String dumpOptions)
                           throws InvalidDumpOptionException,
                                  DumpConfigurationUnavailableException

Sets options for the dump subsystem. The dump option is passed in as an String. Use the same syntax as the -Xdump command-line option, with the initial -Xdump: omitted. See the -Xdump option section on dump agents in the documentation for the OpenJ9 JVM. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is specified an additional check for com.ibm.jvm.ToolDumpPermission will also be made.

Parameters:

dumpOptions - the options string to set

Throws:

InvalidDumpOptionException - if the specified option cannot be set or is incorrect

DumpConfigurationUnavailableException - If the dump configuration cannot be changed because a dump is currently in progress

SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings

NullPointerException - if options is null

queryDumpOptions

public static String[] queryDumpOptions()

Returns the current dump configuration as an array of Strings. The syntax of the option Strings is the same as the -Xdump command-line option, with the initial -Xdump: omitted. See the -Xdump option section on dump agents in the documentation for the OpenJ9 JVM. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Returns:

the options strings

Throws:

SecurityException - if there is a security manager and it doesn't allow the checks required to read the dump settings

resetDumpOptions

public static void resetDumpOptions()
                             throws DumpConfigurationUnavailableException

Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.

Throws:

DumpConfigurationUnavailableException - if the dump configuration cannot be changed because a dump is currently in progress

SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings