JDK-8223666 : SA: debugd options should follow jhsdb style
  • Type: CSR
  • Component: hotspot
  • Sub-Component: svc-agent
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2019-05-10
  • Updated: 2019-05-17
  • Resolved: 2019-05-17
Related Reports
CSR :  
JDK-8223665 - SA: debugd options should follow jhsdb style
Relates :  
JDK-8223814 - SA: jhsdb common help needs to be more detailed
Description
Summary
-------

Make options for debugd mode of jhsdb conform to other jhsdb modes.

Problem
-------

debugd mode of jhsdb was introduced by JDK-8160817. However it uses old-style options as below:

```
[option] <pid> [server-id]	 (to connect to a live java process)
  or
[option] <executable> <core> [server-id] 
                         (to connect to a core file produced by <executable>)
 server-id is an optional unique id for this debug server, needed
 if multiple debug servers are run on the same machine
 where option includes:
   -h | -help	to print this help message
```

jhsdb uses `SALauncher` to start SA tools, and new options were introduced by JDK-8059038. debugd is not compliant with this.

Solution
--------

We can replace all options in debugd with the new jhsdb style.

Specification
-------------

The new command line format for `debugd` will be as per the help out below:
```
$ jhsdb --help
    clhsdb       	command line debugger
    hsdb         	ui debugger
    debugd --help	to get more information
    jstack --help	to get more information
    jmap   --help	to get more information
    jinfo  --help	to get more information
    jsnap  --help	to get more information
```

```
$ jhsdb debugd --help
    --serverid	<unique id for this debug server>
    --exe	<executable image name>
    --core	<path to coredump>
    --pid	<pid of process to attach>
```

For example:

``` jhsdb debugd 1234```

becomes

``` jhsdb debugd --pid 1234```

and 

``` jhsdb debugd /usr/bin/java /tmp/core.1234```

becomes

``` jhsdb debugd --exe /usr/bin/java --core /tmp/core.1234```
Comments
I see there are already plans to release note and otherwise document this change; moving to Approved.
17-05-2019
[~dholmes] David, you are right. Let's leave clarification about full and relative path to JDK-8223814.
16-05-2019
[~sspitsyn] Serguei, I don't think your questions relate directly to this CSR request - which is changing here is the command-line format for the debugd subcommand. The actual semantics are not changing (ie whether the executable must be an absolute or relative path is unchanged). Those details should be documented by the jhsdb help command, along with the mutual exclusive nature of --pid and --exe, but that is the subject of a separate RFE - JDK-8223814
14-05-2019
I've added myself as a reviewer. I also accidentally "pended" this request and can't undo that. [~ysuenaga] please return this to Draft state and then to Finalized. Thanks.
14-05-2019
I have updated the description with angle brackets as below: $ jhsdb debugd --help --serverid <unique id for this debug server> --exe <executable image name> --core <path to coredump> --pid <pid of process to attach> ``` I also have a couple of questions: Q1: Should the <executable image name> be always a full path name or it can be a relative path? Q2: Should the <path to coredump> be always a full path name or it can be a relative path? Q3: Do all other commans (clhsdb, hsdb, jstack, jmap, etc.) currently have the same format or they also need to be updated? (Sorry, I did not have a deal with the SA for a while.) ```
14-05-2019
[~darcy] Joe, hopefully it is clearer now. The help output is showing the new command-line format. I think a RFE should be filed to improve the general jhsdb help output, so that it explains that --pid and --exe are mutually exclusive options. That way this CSR, and thus the associated RFE can proceed.
13-05-2019
It is not clear to me what exactly the request is proposing. Pending the request until clarified.
10-05-2019
The stand-alone tools (jstack etc) use the same "old-style" options as debugd. They are all very clear about the different forms the command can take. jhsdb has lost that with its new approach to the flags.
10-05-2019
Users will make aware this change through error message of jhsdb. jhsdb does not have manpage. Should we add subtask for release note about this? Basically, I believe it is well-known that jhsdb cannot work with both [pid] and [exe]. I guess it is the reason that current help message in jhsdb does not explain it. In fact, help message of jstack in 8u171 shows as below. But all of them are not migrated to jhsdb. ``` $ /usr/local/jdk1.8.0_171/bin/jstack Usage: jstack [-l] <pid> (to connect to running process) jstack -F [-m] [-l] <pid> (to connect to a hung process) jstack [-m] [-l] <executable> <core> (to connect to a core file) jstack [-m] [-l] [server_id@]<remote server IP or hostname> (to connect to a remote debug server) Options: -F to force a thread dump. Use when jstack <pid> does not respond (process is hung) -m to print both java and native frames (mixed mode) -l long listing. Prints additional information about locks -h or -help to print this help message ```
10-05-2019
I've updated the CSR request for grammar etc and also moved the solution to the specification. All the specification needs to show is the new format of the options. That said this new format seem problematic to me as it has lost the information as to how the different options can be used together. The original help shows that you can use: `debugd <pid> [server-id]` (to connect to a live java process) or `debugd <executable> <core> [server-id]` (to connect to a core file) but this information has been lost in the new help, which makes it appear as if you could use all options together on one command-line - which is not the case (the implementation rejects using pid together with exe or core). So while I don't disagree with making things consistent I think more work is needed here.
10-05-2019
Also you state that users of debugd can migrate to the new options, but how will they be made aware of them? Is there a manpage for jhsdb? If so there will need to be a subtask of JDK-8223665 to update that manpage. Otherwise how does this change get communicated? Only via an error when they try to use the old format?
10-05-2019