Skip to content

CAUTION: This site hosts draft documentation for the next release. For published content of the latest release, visit www.eclipse.org/openj9/docs

Java diagnostic command (jcmd) tool

Use the jcmd tool to run diagnostic commands on a specified VM.

Note: Running diagnostic commands can significantly affect the performance of the target VM.

The command syntax is as follows:

jcmd [<options>] [<vmid | display name | 0> <arguments>]

Where:

  • The available <options> are:

    • -l: lists current Java™ processes recognized by the jcmd tool. The list includes VMID, which is usually the process ID (pid) and the display name, which refers to the target Java VM process that can be attached by jcmd. -l is the default option, therefore specifying jcmd without any options also displays the VMIDs.
    • -J: supplies arguments to the Java VM that is running the jcmd command. You can use multiple -J options, for example: jcmd -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes
    • -h: prints the jcmd help

  • <vmid> is the Attach API virtual machine identifier for the Java VM process. This ID is often, but not always, the same as the operating system pid. One example where the ID might be different is if you specified the system property -Dcom.ibm.tools.attach.id when you started the process. In addition to the jcmd command, you can also use the jps command to find the VMID.

    You can also specify the full or partial target Java process display name instead of the VMID. The jcmd tool finds the corresponding VMID of the display name and runs the jcmd command.

    You can specify the display name for a target VM through the com.ibm.tools.attach.displayName system property. If the display name is not set through the system property, then the main class name along with the application arguments is set as the default display name.

    If you specify 0, the jcmd command is sent to all Java processes that are detected by the current jcmd command.

  • The available arguments are:

    • help: shows the diagnostic commands that are available for this VM. This list of commands can vary between VMs.
    • help <command>: shows help information for the specified diagnostic command
    • <command> [<command_arguments>]: runs the specified diagnostic command, with optional command arguments

Examples:

jcmd 31452 Thread.print
jcmd 31452 help Dump.heap
jcmd 31452 Dump.heap myHeapDump

Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9™. For information about the differences between these two implementations, see Switching to OpenJ9.

The tool uses the Attach API, and has the following limitations:

  • Displays information only for local processes that are owned by the current user, due to security considerations.
  • Displays information for OpenJ9 Java processes only
  • Does not show information for processes whose Attach API is disabled. Note: The Attached API is disabled by default on z/OS.

For more information about the Attached API, including how to enable and secure it, see Java Attach API.

See Also