|
| 1 | +--- |
| 2 | +layout: docs |
| 3 | +toc_group: debugging-and-diagnostics |
| 4 | +link_title: Java Diagnostic Command |
| 5 | +permalink: /reference-manual/native-image/debugging-and-diagnostics/jcmd/ |
| 6 | +--- |
| 7 | + |
| 8 | +# Java Diagnostic Command (jcmd) with Native Image |
| 9 | + |
| 10 | +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. |
| 11 | +This support complements existing Native Image monitoring features, including JDK Flight Recorder, heap dumps, and native memory tracking. |
| 12 | + |
| 13 | +## Enabling `jcmd` Support |
| 14 | + |
| 15 | +Support for `jcmd` is disabled by default and must be explicitly enabled at build time. |
| 16 | + |
| 17 | +Use the `--enable-monitoring=jcmd` option to build a native executable with `jcmd` enabled. |
| 18 | +```shell |
| 19 | +native-image --enable-monitoring=jcmd YourApplication |
| 20 | +``` |
| 21 | + |
| 22 | +When enabling support for `jcmd`, you may also want to include additional monitoring features, such as JDK Flight Recorder or heap dumps. |
| 23 | +Including multiple monitoring features during the Native Image build process unlocks access to more diagnostic commands at runtime. |
| 24 | +For example: |
| 25 | +```shell |
| 26 | +native-image --enable-monitoring=jcmd,jfr,heapdump YourApplication |
| 27 | +``` |
| 28 | + |
| 29 | +To use `jcmd` at runtime, start your native executable as usual and obtain its process ID (PID). |
| 30 | +With the PID, you can use `jcmd` to connect to the running native application. |
| 31 | +For example, to list the available commands for a specific executable, run: `jcmd <pid> help`. |
| 32 | +```shell |
| 33 | +jcmd 388454 help |
| 34 | + |
| 35 | +388454: |
| 36 | +The following commands are available: |
| 37 | +GC.heap_dump |
| 38 | +GC.run |
| 39 | +JFR.start |
| 40 | +JFR.stop |
| 41 | +JFR.check |
| 42 | +JFR.dump |
| 43 | +Thread.dump_to_file |
| 44 | +Thread.print |
| 45 | +VM.command_line |
| 46 | +VM.native_memory |
| 47 | +VM.system_properties |
| 48 | +VM.uptime |
| 49 | +VM.version |
| 50 | +help |
| 51 | + |
| 52 | +For more information about a specific command use 'help <command>'. |
| 53 | +``` |
| 54 | + |
| 55 | +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. |
| 56 | +```shell |
| 57 | +native-image --enable-monitoring=jcmd,jvmstat YourApplication |
| 58 | +``` |
| 59 | + |
| 60 | +```shell |
| 61 | +jcmd -l |
| 62 | +1455557 YourApplication |
| 63 | +1455667 jdk.jcmd/sun.tools.jcmd.JCmd -l |
| 64 | +``` |
| 65 | + |
| 66 | +## Supported Diagnostic Commands |
| 67 | + |
| 68 | +The following key-value pairs are supported: |
| 69 | + |
| 70 | +| Name | Included with `--enable-monitoring=` | Description | |
| 71 | +|--------------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------| |
| 72 | +| Compiler.dump_code_cache | Only available with Truffle runtime compilation | Print information about all compiled methods in the code cache. | |
| 73 | +| GC.heap_dump | heapdump | Generate a HPROF format dump of the Java heap. | |
| 74 | +| GC.run | Always available | Call `java.lang.System.gc()`. | |
| 75 | +| JFR.start | jfr | Starts a new JFR recording. | |
| 76 | +| JFR.stop | jfr | Stops a JFR recording. | |
| 77 | +| JFR.check | jfr | Checks running JFR recording(s). | |
| 78 | +| JFR.dump | jfr | Copies contents of a JFR recording to file. Either the name or the recording id must be specified. | |
| 79 | +| Thread.dump_to_file | Always available | Dump threads, with stack traces, to a file in plain text or JSON format. | |
| 80 | +| Thread.print | Always available | Print all threads with stacktraces. | |
| 81 | +| VM.command_line | Always available | Print the command line used to start this VM instance. | |
| 82 | +| VM.native_memory | nmt | Print native memory usage. | |
| 83 | +| VM.system_properties | Always available | Print system properties. | |
| 84 | +| VM.uptime | Always available | Print VM uptime. | |
| 85 | +| VM.version | Always available | Print JVM version information. | |
| 86 | +| help | Always available | Display help information. | |
| 87 | + |
| 88 | +## Performance |
| 89 | + |
| 90 | +Adding `jcmd` support to Native Image has minimal impact on performance when the application is idle. |
| 91 | +However, the performance impact varies significantly depending on the diagnostic commands used and how frequently they are invoked. |
| 92 | +For example, triggering multiple garbage collections will have a much greater overhead than dumping a single native memory tracking report. |
| 93 | +You can use `jcmd <pid> help <command>` to print the help information for a specific command which also lists its expected performance impact. |
| 94 | + |
| 95 | +## Limitations |
| 96 | + |
| 97 | +Currently, this feature is not available on Windows. |
| 98 | + |
| 99 | +### Further Reading |
| 100 | + |
| 101 | +- [Debugging and Diagnostics](DebuggingAndDiagnostics.md) |
| 102 | +- [Build and Run Native Executables with JFR](guides/build-and-run-native-executable-with-jfr.md) |
0 commit comments