8370071: Clarify jcmd Thread.print help message #27861

coffeys · 2025-10-17T08:50:45Z

Simple tweak to jcmd Thread.print help message

jdk_svc test group ran and green

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8370071: Clarify jcmd Thread.print help message (Bug - P4)

Reviewers

Kevin Walls (@kevinjwalls - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/27861/head:pull/27861
$ git checkout pull/27861

Update a local copy of the PR:
$ git checkout pull/27861
$ git pull https://git.openjdk.org/jdk.git pull/27861/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 27861

View PR using the GUI difftool:
$ git pr show -t 27861

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/27861.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-10-17T08:52:40Z

👋 Welcome back coffeys! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-10-17T08:53:54Z

@coffeys This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8370071: Clarify jcmd Thread.print help message

Reviewed-by: kevinw

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 20 new commits pushed to the master branch:

0a97bef: 8369814: G1: Relax card mark and store ordering
e62a7fa: 8342659: Test vmTestbase/nsk/jdi/ObjectReference/referringObjects/referringObjects002/referringObjects002.java failed: Class nsk.share.jdi.TestClass1 was not unloaded
9b9559a: 8369979: Flag UsePopCountInstruction was accidentally disabled on PPC64
... and 17 more: https://git.openjdk.org/jdk/compare/e56db37734aa7cbc0f20ba3fc469f51224f288fa...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2025-10-17T08:54:40Z

@coffeys The following labels will be automatically applied to this pull request:

hotspot-runtime
serviceability

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

mlbridge · 2025-10-17T08:58:45Z

Webrevs

coffeys · 2025-10-17T09:05:21Z

Any issues if I add this sentence to the help output ?

“Use Thread.dump_to_file command for extended threads detail including virtual thread information."

kevinjwalls

Good idea, this could be clearer.

If you want to expand this:
Elsewhere for ThreadDumpToFileDCmd we say:
"Dump threads, with stack traces, to a file in plain text or JSON format."
We could add on: "Includes virtual threads." or add in that fact somehow.

There's also a man page ./src/jdk.jcmd/share/man/jcmd.md where we have the same text for both commands. 8-)

AlanBateman · 2025-10-17T09:30:02Z

src/hotspot/share/services/diagnosticCommand.hpp

  static const char* name() { return "Thread.print"; }
  static const char* description() {
-    return "Print all threads with stacktraces.";
+    return "Print all platform threads with stacktraces.";


The Thread.print section of the jcmd man page can be updated to align with the update description.

If there is space, then we could include "and all mounted virtual threads".

(Note that there was a previous attempt to change this description when the Thread.print was updated to include mounted virtual threads. At the time, the PR feedback was to separate it to a different PR but there wasn't any follow-up on that so good to see it re-visited here)

coffeys · 2025-10-17T10:01:07Z

Good idea, this could be clearer.

If you want to expand this: Elsewhere for ThreadDumpToFileDCmd we say: "Dump threads, with stack traces, to a file in plain text or JSON format." We could add on: "Includes virtual threads." or add in that fact somehow.

There's also a man page ./src/jdk.jcmd/share/man/jcmd.md where we have the same text for both commands. 8-)

Thanks for the man page reminder Kevin. I've added some extra help information also. I think it'll help guide users of these tools. PR updated.

kevinjwalls · 2025-10-17T10:12:12Z

Saying "extended threads detail", or even "extended thread details" is a bit vague. It's not clear what Thread.print misses out, or if this will always be true. Could it be just: "Use Thread.dump_to_file for virtual thread information."

AlanBateman · 2025-10-17T10:09:24Z

src/hotspot/share/services/diagnosticCommand.hpp

  }
  static const char *description() {
-    return "Dump threads, with stack traces, to a file in plain text or JSON format.";
+    return "Dump threads (including virtual), with stack traces, "


If you change it to "Dump all threads" then it would be simpler.

AlanBateman · 2025-10-17T10:14:13Z

src/hotspot/share/services/diagnosticCommand.hpp

-    return "Print all platform threads with stacktraces.";
+    return "Print all platform threads with stacktraces. "
+           "Use Thread.dump_to_file command for extended threads "
+            "detail including virtual thread information.";


Can you try "Print all platform threads, and mounted virtual threads, with stack traces"?

Not sure about the second line. I assume you are proposing to add this in order to created awareness but saying "extended threads detail" is confusing. If a second line is added then it could be very simple, e.g. "The Thread.dump_to_file command will print all threads to a file".

yes - nice to have the "mounted virtual threads" clarity.

"The Thread.dump_to_file command will print all threads to a file". --> Will run with that. thanks.

I think it's useful to hint at these commands when end users are reading such help messages.
(e.g. "I want to print thread information but this command is telling me I only get platform + mounted threads.. what do I use for all threads etc.")

coffeys · 2025-10-17T10:19:44Z

Saying "extended threads detail", or even "extended thread details" is a bit vague. It's not clear what Thread.print misses out, or if this will always be true. Could it be just: "Use Thread.dump_to_file for virtual thread information."

Yes - that's a fair point. The dump_to_file option also prints j.u.c Lock information for virtual theads. (hence extended)
Thread.print prints details of a virtual thread if it's mounted.

but yes, "Use Thread.dump_to_file for virtual thread information." sounds better. Maybe even ""Use Thread.dump_to_file for all thread information." based on Alan's comment.

kevinjwalls · 2025-10-17T10:28:35Z

By: "Use Thread.dump_to_file for all thread information."
do we mean:
"Use Thread.dump_to_file for information on all threads."

coffeys · 2025-10-20T09:46:35Z

Thanks for the reviews

/integrate

openjdk · 2025-10-20T09:47:38Z

Going to push as commit ee35320.
Since your change was applied there have been 45 commits pushed to the master branch:

8c775e2: 8370074: Remove unused code in AbstractDebuggeeTest.java
f158451: 8361366: Allow sorting of member details in lexicographical order
5609ee1: 8370049: [s390x] G1 barrier compareAndExchange does not return old value when compareExchange fails
... and 42 more: https://git.openjdk.org/jdk/compare/e56db37734aa7cbc0f20ba3fc469f51224f288fa...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-10-20T09:47:46Z

@coffeys Pushed as commit ee35320.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

AlanBateman · 2025-10-20T10:03:12Z

src/hotspot/share/services/diagnosticCommand.hpp

-    return "Print all threads with stacktraces.";
+    return "Print all platform threads, and mounted virtual threads, "
+           "with stack traces. The Thread.dump_to_file command will "
+           "print all threads to a file.";


I'm still in two minds about having it mention Thread.dump_to_file. If it is mentioned then it would be better to put in a line break and use "may be used to" that rather than "will".

yes - happy to tweak this in follow on issue if necessary. I think it reads fine as is but let me know the final format and I'll file a new PR.

8370071

b7c0a1b

openjdk bot changed the title ~~8370071~~ 8370071: Clarify jcmd Thread.print help message Oct 17, 2025

openjdk bot added serviceability [email protected] hotspot-runtime [email protected] labels Oct 17, 2025

openjdk bot added the rfr Pull request is ready for review label Oct 17, 2025

kevinjwalls approved these changes Oct 17, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Oct 17, 2025

AlanBateman reviewed Oct 17, 2025

View reviewed changes

man page and better help messages

4d2e42a

openjdk bot removed the ready Pull request is ready to be integrated label Oct 17, 2025

AlanBateman reviewed Oct 17, 2025

View reviewed changes

Further help message tweaks

1d68832

kevinjwalls approved these changes Oct 17, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Oct 17, 2025

openjdk bot added the integrated Pull request has been integrated label Oct 20, 2025

openjdk bot closed this Oct 20, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 20, 2025

AlanBateman reviewed Oct 20, 2025

View reviewed changes

8370071: Clarify jcmd Thread.print help message #27861

8370071: Clarify jcmd Thread.print help message #27861

Uh oh!

Conversation

coffeys commented Oct 17, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Oct 17, 2025

Uh oh!

openjdk bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

coffeys commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kevinjwalls left a comment

Choose a reason for hiding this comment

Uh oh!

AlanBateman Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coffeys commented Oct 17, 2025

Uh oh!

kevinjwalls commented Oct 17, 2025

Uh oh!

AlanBateman Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

AlanBateman Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

coffeys Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

coffeys commented Oct 17, 2025

Uh oh!

kevinjwalls commented Oct 17, 2025

Uh oh!

coffeys commented Oct 20, 2025

Uh oh!

openjdk bot commented Oct 20, 2025

Uh oh!

openjdk bot commented Oct 20, 2025

Uh oh!

AlanBateman Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

coffeys Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

coffeys commented Oct 17, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Oct 17, 2025 •

edited

Loading

openjdk bot commented Oct 17, 2025 •

edited

Loading

mlbridge bot commented Oct 17, 2025 •

edited

Loading

coffeys commented Oct 17, 2025 •

edited

Loading

AlanBateman Oct 17, 2025 •

edited

Loading