- GraalVM for JDK 23 (Latest)
- GraalVM for JDK 24 (Early Access)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
- Getting Started with Native Image
- Guides
- Native Image Basics
- Build Overview
- Reachability Metadata
- Optimizations and Performance
- Debugging and Diagnostics
- Debug Info Feature
- Inspect Tool
- JDK Flight Recorder
- Native Memory Tracking
- Java Diagnostic Command
- Linux Perf Profiler Support
- Points-to Analysis Reports
- Dynamic Features
- Interoperability with Native Code
- LLVM Backend
- Workshops and Labs
This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.
Java Diagnostic Command (jcmd) with Native Image
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.
Enabling jcmd
Support #
Support 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
Supported Diagnostic Commands #
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. |
Performance #
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.
Limitations #
Currently, this feature is not available on Windows.