rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat jcmd.md

jcmd — the JVM diagnostic command hub

# Sends diagnostic commands to a running JVM — flags, heap info, thread dumps, JFR control — superseding most older j* tools.

Conceptsaved 2026-08-09 #java#jvm#tooling#diagnostics#observability

Overview

jcmd is the one diagnostic front door to a live JVM: it attaches to a local process and sends it named diagnostic commands, from printing VM flags to triggering GC, dumping threads or heap, and starting Flight Recorder sessions. Oracle's documented position is that jcmd supersedes the older single-purpose tools (jstack, jmap, jinfo, and partially jstat) — one tool, one attach mechanism, an extensible command set that grows with the JVM.

Key points

  • Invocation: jcmd <pid|main-class> <command>; bare jcmd lists running JVMs (like jps); jcmd <pid> help lists the commands that JVM supports, help <command> its options.
  • Same user, same machine: it uses the local attach mechanism (a handshake over a UNIX socket / named pipe), so it must run as the same OS user as the target JVM — sudo -u appuser jcmd ... in practice; there is no remote jcmd.
  • Everyday commands: VM.flags (effective JVM flags), VM.system_properties, VM.command_line, VM.uptime, VM.version.
  • Memory: GC.heap_info (quick generation sizes/usage), GC.class_histogram (jmap -histo equivalent), GC.heap_dump <file> (hprof), GC.run (request a full GC), VM.native_memory (NMT report, if -XX:NativeMemoryTracking is on).
  • Threads: Thread.print (classic dump, = jstack) and Thread.dump_to_file -format=json (Java 21+, includes virtual threads).
  • JFR: JFR.start name=rec settings=profile, JFR.dump filename=..., JFR.check, JFR.stop — the standard way to run recordings against an already-running process.
  • Set flags live: VM.set_flag toggles the writable (manageable) flags at runtime, e.g. HeapDumpOnOutOfMemoryError.

Examples

jcmd                                   # list JVMs
jcmd 4242 help                         # what can this JVM do?
jcmd 4242 GC.heap_info
jcmd 4242 Thread.print > td-$(date +%s).txt
jcmd 4242 JFR.start name=slow settings=profile duration=120s filename=/tmp/slow.jfr

Related

  • JDK & tools — parent catalogue of the JDK toolchain.
  • jstack — the legacy thread-dump tool jcmd's Thread.print replaces.
  • jmap — legacy heap histogram/dump tool; see GC.* commands.
  • jstat — continuous GC sampling, the one job jcmd does not do well.
  • jps — process listing; bare jcmd covers the same ground.
  • JFR & Mission Control — jcmd is the runtime remote-control for JFR.
  • Performance engineering — where these diagnostics fit a performance investigation.