RFR: 8357828: Add a timestamp to jcmd diagnostic commands

[Thomas Stuefe]

On Wed, 24 Sep 2025 09:09:22 GMT, Ivan Bereziuk <duke at openjdk.org> wrote:

>> see inline\.\.\.
>> 
>> On 9\/24\/25 2\:37 AM\, Thomas Stuefe wrote\:
>>> On Thu\, 18 Sep 2025 14\:57\:44 GMT\, Ivan Bereziuk \<duke at openjdk\.org> wrote\:
>>>
>>>> \`jcmd\` provides great diagnostics but many commands lack a timestamp in their output\.
>>>> Adding a timestamp to the output of some would add value for those debugging JVM data\.
>>>>
>>>> Some diagnostic commands already provide timestamps\. For example \`Thread\.print\` already prints one of \"yyyy\-MM\-dd HH\:mm\:ss\" format\.
>>>>
>>>> Adding timestamps to all diagnostic \`jcmd\` commands with a non\-throw\-away STDOUT\.
>>>>
>>>> The exceptions are\:
>>>> \* \`VM\.uptime\` \- command run with \`\-date\` argument will also print a timestamp\;
>>>> \* \`VM\.system\_properties\` \- already lists timestamp
>>>> \* \`Thread\.dump\_to\_file\` \- the content dumped to file already has a timestamp\;
>>>> \* \`VM\.version\`
>>> \@<!-- -->larry\-cable
>>>> anyone who is parsing the output of jcmd\'s programmatically \.\.\. since
>>> this change can potentially break that code
>>>
>>> yeah\, true
>> 
>> thanks\!
>>> \@<!-- -->Domest0s
>>> Hmm\, rather than breaking compatibility and requiring a CSR\, I now also opt for an option\. We are usually not so strict with changing individual commands\, but I agree with Larry that changing the format of all commands may be a problem\.
>> 
>> cheers\!
>>>
>>> Thinking this a bit further\. We may have the same discussion in the future whenever we do fundamental changes to jcmd output\.
>> 
>> agreed\!
>>>
>>> As an arbitrary example\, let\'s say someone wants to report the jcmd runtime back at the end of every command \(I recently needed that\, but abandoned the PR\)\. E\.g\. a trailing \"321ms\"\. Or some other statistics or process specs\. Do we want a new diagnostic switch every time\? That could get confusing quickly\, and these switches need testing\.
>> 
>> agreed
>>>
>>> How about a single \"enable jcmd legacy output format\" setting\. By default on\. Behind this setting we guard all future changes that severely change the output of commands\. Anyone wanting a stable output would define that setting\.
>> 
>> agreed
>>>
>>> And how about making this switch a standard \*jcmd\* option\, not a JVM setting\? Typically\, this decision is made by the analyst running jcmd\. That is the person wanting to post\-process the output\. A JVM switch means the analyst has to restart the JVM with new command\-line parameters\. That is uncomfortable\, and the analyst may even be able to do that \(often ca...
>
>> anyone who is parsing the output of jcmd's programmatically ... since this change can potentially break that code
> 
> @tstuefe Do you think we would need a CSR for this kind of change?

@Domest0s Let's see if everyone agrees on this.

My proposal would entail
- adding a new standard option to jcmd
- somehow funneling that option to the JVM
- the option should be optional, so that:
  - old jcmd still works with new JVMs (and produces legacy jcmd output)
  - new jcmd still works with old JVMs (and produces legacy jcmd output)

How complex would this be? There are two approaches to this. You can either create a new attach listener protocol (we already have ATTACH_API_V2 vs ATTACH_API_V1, so the precedence is there). Or, you can expand the jcmd parsing (see `jcmd(AttachOperation* op, attachStream* out)` in attachListener.cpp).

Not sure whether this would be complex. I understand if this is expanding the scope of your PR too much, in which case I think you should add a new JVM command line option that preserves legacy jcmd output format.

I think you need a CSR in both cases. Not exactly because compatibility would be broken (the jcmd output should stay the same unless this option is explicitly enabled), but because it makes sense to think a bit about the format of this new jcmd option or this new command line flag, and to make the new command line flag product.

Just my 5 cents, let's see what others think first

-------------

PR Comment: https://git.openjdk.org/jdk/pull/27368#issuecomment-3329641686