server dump command

The server dump command creates a snapshot of a server and saves the result into an archive file for further tuning and diagnosis.

This command is useful for problem diagnosis of an Open Liberty server because the resulting file contains server configuration, log information, and details of the deployed applications in the work area directory. The command can be applied to either a running or a stopped server.

For a running server, the following information is also included:

  • State of each OSGi bundle in the server

  • Wiring information for each OSGi bundle in the server

  • Component list that is managed by the Service Component Runtime (SCR) environment

  • Detailed information of each component from SCR

  • Configuration administration data of each OSGi bundle

  • Information about registered OSGi services

  • Runtime environment settings such as Java virtual machine (JVM), heap size, operating system, thread information, and network status

The resulting file is created by using UTF-8 encoding for entry names, so the tool that you use to open the file must be able to use UTF-8 encoding for entry names. The jar command in a Java SDK uses this format.

Usage examples

Create a dump file of thread information from the myserver server in a ZIP archive called myserver.zip:

server dump myserver --archive="myserver.zip" --include=thread

Create a snapshot of the myserver server status in a ZIP archive called myserver.zip:

server dump myserver --archive=myserver.zip --include=heap

Syntax

Run the command from the path_to_liberty/wlp/bin directory.

server dump serverName [options]
serverName

The name of the server to run the command against. If you do not specify a server name, the command uses defaultServer for the name value. If no existing server in the wlp/usr/servers directory is named defaultServer, the command fails when no server name is specified.

Options

Options for the server dump command
OptionDescription

--archive=path_to_the_target_archive_file

Specifies a target file for the package or dump operation. This path can be either a relative path, which is relative to the installation root directory of Open Liberty, or an absolute path. The default archive target is a compressed file with the server name, which is stored in the installation root directory. Use quotation marks if the value contains spaces. You can use this option for both package and dump operations.

If you specify a .jar extension for your archive file name, the server command creates a new self-extracting archive file from which the Open Liberty server can be installed by using the java command.

--include=diagnose_option,diagnose_option,…​

Specifies the type of diagnostic information to be captured. The value of --include is a comma-delimited list, which can contain one or more of the following values:

  • heap is used to help diagnose excessive memory consumption and memory leaks. The dump shows live objects in the memory and references between them. On IBM J9 virtual machines, the resulting file is named heapdump.date.time.processID.sequenceNumber.phd. On HotSpot virtual machines, the resulting file is named java.date.time.processID.sequenceNumber.hprof.

  • system is also used to help diagnose excessive memory consumption and memory leaks, but a system dump also helps find defects in the virtual machine. System dumps are only supported on IBM J9 virtual machines. The resulting file is named core.date.time.processID.sequenceNumber.dmp.

  • thread is used to help diagnose hung threads and deadlocks. Thread dumps can sometimes be used to diagnose excessive CPU issues. On IBM J9 virtual machines, the resulting file is named javacore.date.time.processID.sequenceNumber.txt. On HotSpot virtual machines, the resulting file is named javadump.date.time.processID.sequenceNumber.txt.

The thread dump type is supported only when the server is running on the Java SDK. If the server is started with a JRE, an error is reported indicating that the server does not support the dump type. This restriction applies to HotSpot virtual machines only; the thread Java dump type is supported on any IBM JVM (JRE or SDK).

Exit codes

The following exit codes are available for the server dump command and the equivalent executable JAR file ws-server.jar:

Exit codes for the server dump command
CodeExplanation

0

This code indicates successful completion of the requested operation.

1

This code indicates invocation of a redundant operation. For example, starting a started server or stopping a stopped server. This code might also be returned by JVM if invalid Java options are used.

4

This code indicates that an unsupported action was called on a stopped server. For example, the server is not running when the dump action is called.

>=20

Exit codes that are greater than or equal to 20 indicate that an error occurred while performing the request. Messages are printed and captured in log files with more information about the error.

See also