Documentation Contents
Java Platform, Standard Edition Troubleshooting Guide
Contents Previous Next

# 2.6 The jcmd Utility

The `jcmd` utility is used to send diagnostic command requests to the JVM, where these requests are useful for controlling Java Flight Recordings, troubleshoot, and diagnose JVM and Java Applications. It must be used on the same machine where the JVM is running, and have the same effective user and group identifiers that were used to launch the JVM.

For more details on `jcmd` syntax and other usage details, see the `jcmd` command man page.

A special command `jcmd <process id/main class> PerfCounter.print` prints all performance counters in the process.

The command `jcmd <process id/main class> <command> [options]` sends the actual command to the JVM.

Example 2-1 shows diagnostic command requests to JVM using `jcmd` utility.

Example 2-1 Diagnostic Command Requests with jcmd Utility

    > jcmd
    5485 sun.tools.jcmd.JCmd
    2125 MyProgram

    > jcmd MyProgram help (or "jcmd 2125 help")
    2125:
    The following commands are available:
    JFR.stop
    JFR.start
    JFR.dump
    JFR.check
    VM.native_memory
    VM.check_commercial_features
    VM.unlock_commercial_features
    ManagementAgent.stop
    ManagementAgent.start_local
    ManagementAgent.start
    Thread.print
    GC.class_stats
    GC.class_histogram
    GC.heap_dump
    GC.run_finalization
    GC.run
    VM.uptime
    VM.flags
    VM.system_properties
    VM.command_line
    VM.version
    help

    > jcmd MyProgram help Thread.print
    2125:
    Thread.print
    Print all threads with stacktraces.

    Impact: Medium: Depends on the number of threads.

    Permission: java.lang.management.ManagementPermission(monitor)

    Syntax : Thread.print [options]

    Options: (options must be specified using the <key> or <key>=<value> syntax)
            -l : [optional] print java.util.concurrent locks (BOOLEAN, false)

    > jcmd MyProgram Thread.print
    2125:
    2014-07-04 15:58:56
    Full thread dump Java HotSpot(TM) 64-Bit Server VM (25.0-b69 mixed mode):
    ...

The following sections describe some useful commands and troubleshooting techniques with `jcmd` utility.

- Useful Commands for jcmd Utility

- Troubleshoot with jcmd Utility

## 2.6.1 Useful Commands for jcmd Utility

The available diagnostic command may be different in different versions of HotSpot VM; therefore, using `jcmd <process id/main class> help` is the best way to see all available options. The following are some of the most useful commands that were in the tool since JDK 8. Remember you can always use `jcmd <process id/main class> help <command>` to get any additional options to these commands.

- Print full HotSpot and JDK version ID

  `jcmd <process id/main class> VM.version`

- Print all the system properties set for a VM

  There can be several hundred lines of information displayed.

  `jcmd <process id/main class> VM.system_properties`

- Print all the flags used for a VM

  Even if you have provided no flags, some of the default values will be printed, for example initial and maximum heap size.

  `jcmd <process id/main class> VM.flags`

- Print the uptime in seconds

  `jcmd <process id/main class> VM.uptime`

- Create a class histogram

  The results can be rather verbose, so you can redirect the output to a file. Both internal and application specific classes are included in the list. Classes taking the most memory are listed at the top, and classes are listed in a descending order.

  `jcmd <process id/main class> GC.class_histogram`

- Create a heap dump (hprof dump)

  `jcmd GC.heap_dump filename=Myheapdump`

  This is the same as using `jmap -dump:file=<file> <pid>`, but `jcmd` is the recommended tool to use.

- Create a heap histogram

  `jcmd <process id/main class> GC.class_histogram filename=Myheaphistogram`

  This is the same as using `jmap -histo <pid>`, but `jcmd` is the recommended tool to use.

- Print all threads with stack traces

  `jcmd <process id/main class> Thread.print`

## 2.6.2 Troubleshoot with jcmd Utility

The `jcmd` utility provides the following troubleshooting options:

- Start a recording

  For example, to start a 2-minute recording on the running Java process with the identifier `7060` and save it to myrecording.jfr in the current directory, use the following:

  `jcmd 7060 JFR.start name=MyRecording settings=profile delay=20s duration=2m filename=C:\TEMP\myrecording.jfr`

- Check a recording

  The `JFR.check` diagnostic command checks a running recording. For example:

  `jcmd 7060 JFR.check`

- Stop a recording

  The `JFR.stop` diagnostic command stops a running recording and has the option to discard the recording data. For example:

  `jcmd 7060 JFR.stop`

- Dump a recording

  The `JFR.dump` diagnostic command stops a running recording and has the option to dump recordings to a file. For example:

  `jcmd 7060 JFR.dump name=MyRecording filename=C:\TEMP\myrecording.jfr`

- Create a heap dump

  The preferred way to create a heap dump is

  `jcmd <pid> GC.heap_dump filename=Myheapdump`

- Create a heap histogram

  The preferred way to create a heap histogram is

  `jcmd <pid> GC.class_histogram filename=Myheaphistogram`

Contents Previous Next

Copyright © 1993, 2018, Oracle and/or its affiliates. All rights reserved.
Contact Us