- 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()
andSnapDump()
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()
andsnapDumpToFile()
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 thejavaDumpToFile()
,systemDumpToFile()
,heapDumpToFile()
andsnapDumpToFile()
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.
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 usesetDumpOptions(String)
to restore that configuration after a call to setDumpOptions("none") to clear all dump agent configuration.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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.
-
-
-
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 supportSecurityException
- 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 supportSecurityException
- 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 supportSecurityException
- 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 supportSecurityException
- 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.
- 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 invalidSecurityException
- 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.
- 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 invalidSecurityException
- 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.
- 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 invalidSecurityException
- 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.
- 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 invalidSecurityException
- 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 supportSecurityException
- if there is a security manager and it doesn't allow the checks required to trigger this dumpInvalidDumpOptionException
- If the dump options are invalid or the dump operation failsNullPointerException
- 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 incorrectDumpConfigurationUnavailableException
- If the dump configuration cannot be changed because a dump is currently in progressSecurityException
- if there is a security manager and it doesn't allow the checks required to change the dump settingsNullPointerException
- 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 progressSecurityException
- if there is a security manager and it doesn't allow the checks required to change the dump settings
-
-