docs/reference-manual/native-image/JCmd.md
Native Image now supports the Java Diagnostic Command (jcmd), enabling users to interact with native executables using the same jcmd tool they use for Java applications.
This support complements existing Native Image monitoring features, including JDK Flight Recorder, heap dumps, and native memory tracking.
jcmd SupportSupport for jcmd is disabled by default and must be explicitly enabled at build time.
Use the --enable-monitoring=jcmd option to build a native executable with jcmd enabled.
native-image --enable-monitoring=jcmd YourApplication
When enabling support for jcmd, you may also want to include additional monitoring features, such as JDK Flight Recorder or heap dumps.
Including multiple monitoring features during the Native Image build process unlocks access to more diagnostic commands at runtime.
For example:
native-image --enable-monitoring=jcmd,jfr,heapdump YourApplication
To use jcmd at runtime, start your native executable as usual and obtain its process ID (PID).
With the PID, you can use jcmd to connect to the running native application.
For example, to list the available commands for a specific executable, run: jcmd <pid> help.
jcmd 388454 help
388454:
The following commands are available:
GC.heap_dump
GC.run
JFR.start
JFR.stop
JFR.check
JFR.dump
Thread.dump_to_file
Thread.print
VM.command_line
VM.native_memory
VM.system_properties
VM.uptime
VM.version
help
For more information about a specific command use 'help <command>'.
You might find it useful to also enable the jvmstat monitoring feature so your native executable can be discovered and listed with jcmd -l or jcmd with no arguments provided.
native-image --enable-monitoring=jcmd,jvmstat YourApplication
jcmd -l
1455557 YourApplication
1455667 jdk.jcmd/sun.tools.jcmd.JCmd -l
The following key-value pairs are supported:
| Name | Included with --enable-monitoring= | Description |
|---|---|---|
| Compiler.dump_code_cache | Only available with Truffle runtime compilation | Print information about all compiled methods in the code cache. |
| GC.heap_dump | heapdump | Generate a HPROF format dump of the Java heap. |
| GC.run | Always available | Call java.lang.System.gc(). |
| JFR.start | jfr | Starts a new JFR recording. |
| JFR.stop | jfr | Stops a JFR recording. |
| JFR.check | jfr | Checks running JFR recording(s). |
| JFR.dump | jfr | Copies contents of a JFR recording to file. Either the name or the recording id must be specified. |
| Thread.dump_to_file | Always available | Dump threads, with stack traces, to a file in plain text or JSON format. |
| Thread.print | Always available | Print all threads with stacktraces. |
| VM.command_line | Always available | Print the command line used to start this VM instance. |
| VM.native_memory | nmt | Print native memory usage. |
| VM.system_properties | Always available | Print system properties. |
| VM.uptime | Always available | Print VM uptime. |
| VM.version | Always available | Print JVM version information. |
| help | Always available | Display help information. |
Adding jcmd support to Native Image has minimal impact on performance when the application is idle.
However, the performance impact varies significantly depending on the diagnostic commands used and how frequently they are invoked.
For example, triggering multiple garbage collections will have a much greater overhead than dumping a single native memory tracking report.
You can use jcmd <pid> help <command> to print the help information for a specific command which also lists its expected performance impact.
Currently, this feature is not available on Windows.