Liberica JDK: Using jcmd locally, containerized, and remotely

jcmd is the command line executed with JVM diagnostic tools shipped with OpenJDK. Before the introduction of jcmd, there were multiple tools to run live and postmortem diagnostics for JVM. jcmd became a to-go utility for live diagnostics of JVM executed from the command line (e.g., dumping threads or inspecting JVM configuration). The postmortem diagnostics are performed with other tools.

There exists a wide range of tools in the JVM ecosystem, including graphical and web, so why use the command line tools? There are a few reasons:

jcmd displays a long list of commands (which is included at the end of the document), and a lot of them work on the low level of programming. Here is an overview of operations available via jcmd:

Next, we will overview the typical jcmd workflow with examples.

Usually, jcmd is added to PATH when installing OpenJDK. If, for some reason, it does not exist in your path, you can find binary under bin at your OpenJDK installation directory.

The first thing jcmd requires is the PID of the JVM process you want to work with. There are multiple ways to get the PID of a JVM, and one of them is to list locally running JVM processes with jcmd itself.

Executing jcmd without parameters will list locally running JVMs and their respective PIDs.

As you see, jcmd includes itself in the list, because it is implemented in Java.

Once you’ve got a PID, you can list commands exposed by the JVM.

The list of commands may vary between versions of JDK.

Taking a thread dump is a common task beneficial for quick diagnosis. You can execute the Thread.print command for that.

Another typical action is dumping a heap of JVM.

The command above will create a "dump.hprof" file in the current directory. You can open this file with VisualVm or Eclipse Memory Analyzer Tool for detailed analysis.

Notice that we provided the absolute path (via pwd command). The relative path is interpreted from the working directory of JVM, which is not the best place for heap dump creation.

If you struggle to recall arguments for a specific command, you can use built-in help.

An excellent addition in OpenJDK 11 and above is the -gz option that helps to make a compressed heap dump. Heap dumps compression is usually effective, saving both space and disk IO.

When developing and running Java applications on your desktop, jcmd works excellent. The main issue is running jcmd as the same user as the JVM you are connecting to. jcmd and other JDK tools work seamlessly on all supported platforms.

But you often have to run software in the containers or on some kind of remote host. jcmd is essential for ad hoc diagnostics of Java applications, and the ability to use it in a variety of circumstances is vital.

Running a JVM in a container is pretty standard these days, so let’s see how jcmd deals with containers.

There are two protocols implemented in jcmd — discovery and commands.

jattach is a compact tool written in C that implements the protocol described above.

jattach is very handy if jcmd is not available for some reason, such as you have to use stripped-down JRE instead of JDK. Unlike jcmd, which you cannot copy as a binary, jattach is a standalone binary of just a few kilobytes. It is easy to download and run when you need it.

With jattach "jcmd …" you can enjoy the full functionality of jcmd from JDK. Note that you need to input the whole command starting with jcmd in quotes.

We mentioned the lack of need for upfront configuration as one of the advantages of jcmd. Sometimes though, JMX access is available while terminal access is not.

In this case, you cannot use jcmd, but precisely the same list of commands is available via JVM.

We suggest using Liberica Mission Control.

Execute Mission Control, connect to the remote process with JMX Console and switch to the Diagnostics Commands tab.

As you see, the very same list of commands from jcmd is present there.

Commands are exposed as MBean operations, so they are available for other tools too.

The "typical" JConsole. Operations are available under com.sun.management/DiagnosticCommand MBean.

Unfortunately, JConsole cannot deal with argument types, so only the operations without parameters can be invoked.

SJK is another open source tool for JVM diagnostics. It is capable of invoking any MBean operations through a JMX connection. If you need to invoke the jcmd command from the terminal on a remote JVM, you can use SJK.

For more information about a specific command use help <command>.

Commands that produce files do that relative to the JVM working directory. If a JVM is running in a container, then the container’s FS will be used. If you need to take a heap dump of a JVM running in a container, it is better to use a path mounted from the host as a filename for the dump file.

If no good mount is available, you can fall back to /proc/PID/root/ mount point to access the container’s file system from the host. Note that it will not help if the container is running in a VM or remote host.

While the list of commands supported by jcmd is long, many are more useful for JVM engineers than application developers. In any case, we would like to point out all of them.

jcmd is a simple tool with a command line interface. You can use it for troubleshooting tasks, such as taking thread and heap dumps, introspecting JVM configuration, controlling flight recorder, and some others.

Starting with JDK 11, jcmd is built with excellent support for Linux containers. In the case of using the containers, there are few key points to keep in mind:

If you do not have jcmd installed on the host or in the container, jattach is a reliable and lightweight drop-in replacement that can execute the same commands.