Generating a Liberty server dump from the command line

From the command line, you can use the server dump or server javadump command to capture status information for a Liberty server.

About this task

The following information applies to the server dump command.

The server dump command is useful for problem diagnosis of a Liberty server because the result file contains server configuration, log information, and details of the deployed applications in the workarea 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

A default server configuration puts server log files in a subdirectory under the server directory, for example, in the WLP_HOME/usr/servers/<SERVER_NAME>/logs directory. By default, these server logs are added to server dumps.

You can specify an alternate directory for the server logs. These logs are placed in the server dumps.

If you specify an alternate directory with the LOG_DIR environment variable, the logs are placed in the server dump.
Due to a limitation, if you specify an alternate directory with the server.env file or the server.xml file, the logs are not placed in the server dump.

When an alternate location is configured, two folders are created within the server dump archive. Log files from the default location are placed in the server dump file in the WLP_HOME/usr/servers/<SERVER_NAME>/logs directory that was mentioned previously. Logs from an alternate location are placed in the server dump file in the logs_external/<log_name> directory. The default location is included even when an alternate location is configured because server logs can still be present in the default location. See the following example.

The LOG_DIR environment variable is set to the following value.
```
LOG_DIR = /alt_root/server1/logs
```
Logs are placed in the following directories in the server dump file.
```
package_file_name.dump.zip/logs
package_file_name.dump.zip/logs_external/logs
```
- The files in the logs subdirectory are from the WLP_HOME/usr/<SERVER_NAME>/logs directory.
- Files in the logs_external/logs subdirectory are files from the /alt_root/server1/logs directory.

The following information applies to the server javadump command.

The server javadump command is useful for diagnosing problems at the JVM level, such as hung threads, deadlocks, excessive processing, excessive memory consumption, memory leaks, and defects in the virtual machine. The command can be used only on a running server. Each dump type creates a file, but not all dump types are supported by all virtual machines. See Server command options.

The default directory for dump files is ${server.output.dir}. To set a different default directory, you must use an IBM® JVM and set the following environment variables:

IBM_HEAPDUMPDIR
IBM_COREDIR
IBM_JAVACOREDIR

Procedure

Open a command line, then change directory to the wlp/bin directory.
Capture the status information by using one of the following command-line tools. If you do not specify a server name, defaultServer is used.
- To create a snapshot of the server status, use server dump command.
  - server dump server_name --archive=package_file_name.dump.zip --include=heap
    where package_file_name.dump.zip is a file name that you choose. This file name can include a full path name. If the full path is omitted, a compressed file called package_file_name.dump.zip is created in default directory ${server.output.dir}.
  - server dump server_name --archive=package_file_name.dump.pax --include=heap
    where package_file_name.dump.pax is a file name that you choose. This file name can also include a full path. If the full path is omitted, a compressed file called package_file_name.dump.pax is created in default directory ${server.output.dir}.
  The --include parameter is optional. You can request additional memory dump types. For example, --include=heap option requests a heap dump; --include=thread,heap,system option requests a thread dump, a heap dump, and a system dump.
- To create a snapshot of the JVM status, use server javadump command.
  - server javadump server_name --include=heap
  - server javadump server_name --include=heap
  The --include parameter is optional. You can request additional memory dump types. For example, --include=heap option requests a heap dump; --include=heap,system option requests a heap dump and a system dump. The output files are created in the default directory ${server.output.dir}. To set a different default directory, you must use an IBM JVM and set the IBM_HEAPDUMPDIR, IBM_COREDIR, and IBM_JAVACOREDIR environment variables.
Note: 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.

Results

If the specified server does not exist, the command does not succeed. If the specified server exists, a result file is created that contains the status information of the server.