Summary

Update the thread dump generated by com.sun.management.HotSpotDiagnosticMXBean.dumpThreads and the jcmd <pid> Thread.dump_to_file diagnostic command to include thread state and lock information.

Update com.sun.management.HotSpotDiagnosticMXBean.dumpThreads to describe the structure of the JSON thread dump.

Problem

The thread dump generated by HotSpotDiagnosticMXBean.dumpThreads and jcmd <pid> Thread.dump_to_file doesn't include lock information that is important for troubleshooting.

The JSON format thread dump is intended to be read by tools but the structure is not documented.

Solution

Update the thread dump, both plain text format and JSON format, to include the following:

• the thread state
• the "parkBlocker" when a thread is parked. If the parkBlocker is an AbstractOwnableSynchronizer then the owner of the exclusive mode synchronizer is also included.
• the object that the thread is blocked on when blocked on monitor enter
• the locks (object monitors) that were acquired in each frame
• where possible, the object that a thread is waiting on when waiting in Object.wait.

Specification

HotSpotDiagnosticMXBean.dumpThreads is updated to link to a JSON object that describes the thread dump format. The linked file (threadDump.schema.json) is attached.

@@ -116,6 +116,13 @@ public interface HotSpotDiagnosticMXBean extends PlatformManagedObject {
      * {@code outputFile} parameter must be an absolute path to a file that
      * does not exist.
      *
+     * <p> When the format is specified as {@link ThreadDumpFormat#JSON JSON}, the
+     * thread dump is generated in JavaScript Object Notation.
+     * <a href="doc-files/threadDump.schema.json">threadDump.schema.json</a>
+     * describes the thread dump format in draft
+     * <a href="https://tools.ietf.org/html/draft-json-schema-language-02">
+     * JSON Schema Language version 2</a>.
+     *
      * <p> The thread dump will include output for all platform threads. It may
      * include output for some or all virtual threads.
      *
@@ -151,6 +158,7 @@ public static enum ThreadDumpFormat {
         TEXT_PLAIN,
         /**
          * JSON (JavaScript Object Notation) format.
+         * @spec https://datatracker.ietf.org/doc/html/rfc8259 JavaScript Object Notation
          */
         JSON,
     }

There are no updates to the jcmd man page at this time but we may re-visit this before the CSR is finalized.