src: update --inspect hint text #11207

joshgav · 2017-02-06T22:35:56Z

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

src, inspector

Removes "experimental" warning.
Prints ws://_ip_:_port_:/_uuid_ for all IDs.
Refers to nodejs.org guide for more details.

Output is:

Debugger listening on ws://127.0.0.1:9229/11cb1a9c-5994-4a83-a681-f4213b0fdd12
For help see https://nodejs.org/en/docs/inspector

/cc @nodejs/diagnostics

joyeecheung · 2017-02-07T03:01:38Z

src/inspector_socket_server.cc

+
+  fprintf(out, "\nFor more info go to %s\n\n", GUIDE_URL);
+
+  fprintf(out, MapsToString(this->GetListResponse()).c_str());


Maybe just fprintf(out, "http://%s:%d/json/list", this->host().c_str(), this->port()); instead of printing the whole response?

cjihrig · 2017-02-07T14:15:45Z

This seems noisy (both the output and the diff). Users almost certainly will never care about the array at the end. Couldn't you just add the piece that links to the debugging guide?

joshgav · 2017-02-07T15:47:12Z

@cjihrig

Couldn't you just add the piece that links to the debugging guide?

Sure, my goal in the initial commit was to share a few options for review. A tricky part is that users may need the UUID or full ws://... URL if connecting manually.

mavericken · 2017-02-09T16:49:03Z

I think we should at least keep both the the documentation link and the chrome URL. Also, we should err on the side of providing more help, even if it is at the cost of being too verbose.

I have an idea I am reluctant to mention because I feel it would be overkill, but I'll do it anyways. If we want to eliminate noise and be helpful, a solution would be to link to a single HTML page ( perhaps with URL parameters) which displays any dynamic links or configurations for various tools.

jkrems · 2017-02-24T17:23:18Z

One observation I made was that people seem to be unaware of the automatic links in chrome://inspect and aren't that happy with having to copy&paste the URL (see the advent of chrome extensions that duplicate chrome://inspect). So I'm not sure printing the chrome-devtools:// url is doing anyone any favors. It seems to funnel people into a bad workflow.

jkrems · 2017-04-03T19:30:30Z

Do we want to update this PR and remove the experimental warnings or would that require another PR?

joshgav · 2017-04-04T22:16:54Z

@jkrems I'll update this one in next couple days, thanks!

joshgav · 2017-04-05T18:02:59Z

@jkrems @ofrobots @eugeneo updated to an official proposal, PTAL.

This is per next steps in Diag WG meeting: https://github.com/nodejs/diagnostics/blob/master/wg-meetings/2017-03-23.md#wip-inspector-hint-text-update-11207

This removes the chrome-devtools:// URL and only provides a ws://... URL. The copy-pastability of the chrome-devtools URL has been raised in the above meeting; would it be possible for chrome://inspect to accept the ws://... URL and transform it to the chrome-devtools URL? That would actually make copy-pasting easier since the URL is shorter.

Thanks!

eugeneo · 2017-04-05T18:20:05Z

Chrome DevTools are looking at different options to help the users start debugging the Node (e.g. shorter/bookmarkable URL, easier discovery, etc) but there is no immediate solution that would be more convenient to copying the URL from the console to the browser address bar.

Even to copy/pasting the WS URL to chrome://inspect requires the users to read the guide and remember "chrome://inspect" URL itself. It is an extra step whenever the Node is restarted - and judging from the UUID introduction, this will be even bigger pain.

Removing the URL at this time will definitely break the workflow of many users. I believe it should be kept it a smoother workflow is implemented and is deployed in Chrome stable...

jkrems · 2017-04-17T15:19:11Z

My personal vote would be for the ws://<host>:<ip>/<uuid> format that is implemented here. "Open this URL in Chrome" isn't a great experience past the very first interaction. I would be surprised if many users are using that flow and are remotely happy with it. From what I'm aware people are either migrating to Chrome extensions, use IDEs like vscode to start the node process, or go for chrome://inspect. All of these are reasonable, convenient workflows but none of them really needs a full DevTools URL printed to stderr.

(*) I have a particular bias against the DevTools URL because I keep hearing people complain about having to copy and paste the URL on every restart. They think it's the "normal"/"suggested"/"official" workflow and so they don't check the docs for better ways. I'd rather not keep re-posting the same answers to even more developers... ;)

joshgav · 2017-04-19T13:13:25Z

@Trott @nodejs/ctc the following is where your opinions would be helpful, thanks! I think you can reflect these via approvals to this PR and/or rejections and comments in this thread. I tagged ctc-agenda cause I think a brief live discussion would be helpful. There's a possibility I might miss the meeting today cause of travel 😞 (will be back more consistently starting next week!), @jkrems any possibility you could attend the CTC meeting today as well to help explain if needed? Thanks!

Without further ado 😉 here's that explanation:

The current hint text (in master) is:

Debugger listening on 127.0.0.1:9229.
To start debugging, open the following URL in Chrome:
    chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/eff03f13-55c9-4fef-8bf4-f938376ac9d6

The hint text proposed in this PR is:

Debugger listening on ws://127.0.0.1:9229/11cb1a9c-5994-4a83-a681-f4213b0fdd12
For help see https://nodejs.org/en/docs/guides/debugging_getting_started

The main questions to be reviewed by the CTC are:

Whether or not to include To start debugging...chrome-devtools://... in the hint text or remove it.
Whether to provide the entire ws://host:port/uuid URL or just host:port in the first line.

My opinion is that the message proposed in this PR is easier to read and understand, mostly avoids the >80 column overflow with the long chrome-devtools URL, (see e.g. #7141) and provides enough information to get started without being overly verbose.

Although the extra For help see... line isn't strictly necessary, I think it aligns with our spirit of being as helpful as possible to our users. It also helps address usability concerns due to removal of the DevTools URL. Finally, it's easier to update that doc for changes in clients rather than introduce changes here in the runtime (e.g. if Chrome DevTools itself introduces a new syntax).

Removing the chrome-devtools:// text will also reduce the somewhat incorrect association of Node/V8's Inspector with Chrome DevTools and other tools, reflected in issues such as #11591, #10410, #9382, and #8438; and as alluded to by @jkrems above (comment).

Including the UUID in the default output will also be helpful to some users, see #11496, #11701, #9185, and #10578. For the same reason prepending the scheme (i.e. ws) makes it more obvious that WebSocket rather than HTTP is the protocol in use.

Since Inspector is just now emerging from experimental status this change isn't yet semver-major, but I think it would be after 8.0.0, so want to land this before the final release, one of the reasons I tagged ctc-agenda.

Thanks for your help!

joshgav · 2017-04-19T13:30:00Z

Cherry-picked update to node-inspect landed in #12363.

New CI: https://ci.nodejs.org/job/node-test-pull-request/7516/

jasnell · 2017-04-19T14:24:04Z

I'm +1 on the proposed changed hint text in this PR.

jkrems · 2017-04-19T14:56:18Z

any possibility you could attend the CTC meeting today as well to help explain if needed?

@joshgav I could join for the first couple of minutes but have some conflicting meetings. With the delay of the release (and some CTC members already chiming in here) it seems less urgent..?

Fishrock123 · 2017-04-19T16:19:18Z

Maybe we can get https://nodejs.org/en/inspector or similar rather than https://nodejs.org/en/docs/guides/debugging_getting_started?

ofrobots · 2017-04-19T16:24:00Z

Maybe we can get https://nodejs.org/en/inspector or similar rather than https://nodejs.org/en/docs/guides/debugging_getting_started?

+1. The debugging_getting_started guide indeed seem to be a big wall of text. A different doc with very clear links to how to open various different debuggers (VSCode, DevTools, etc.) would be a lot more usable.

Trott · 2017-04-19T22:44:36Z

From the @nodejs/website perspective, https://nodejs.org/en/docs/inspector might be slightly better information architecture than https://nodejs.org/en/inspector. Either is 👍 by me, FWIW.

mhdawson · 2017-04-26T20:08:31Z

I'm +1 for something like https://nodejs.org/en/docs/inspector. Seems better than the guide.

* Removes "experimental" warning. * Prints ws://_ip_:_port_:/_uuid_ for all IDs. * Refers to nodejs.org guide for more details. PR-URL: nodejs#11207 Reviewed-By: _tbd_ Reviewed-By: _tbd_

joshgav · 2017-05-03T18:18:25Z

Removed lots of text from the doc per @ofrobots' feedback and moved to https://nodejs.org/en/docs/inspector in nodejs/nodejs.org#1216, PTAL.

Updated link in this PR too.

I'll land this once the updated doc lands in nodejs.org. If any are still opposed please comment now!

joshgav · 2017-05-04T15:00:28Z

Thanks all. This PR landed in 6ade7f3.

The docs PR landed in nodejs/nodejs.org@13eaf4c

* Removes "experimental" warning. * Prints ws://_ip_:_port_:/_uuid_ for all IDs. * Refers to nodejs.org guide for more details. PR-URL: #11207 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <mhdawson@ibm.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>

PR-URL: #1216 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jan Krems <jan.krems@gmail.com>

* Removes "experimental" warning. * Prints ws://_ip_:_port_:/_uuid_ for all IDs. * Refers to nodejs.org guide for more details. PR-URL: nodejs#11207 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <mhdawson@ibm.com> Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. dont-land-on-v4.x inspector Issues and PRs related to the V8 inspector protocol labels Feb 6, 2017

joshgav mentioned this pull request Feb 6, 2017

inspector,doc: update hint text, add guide #8978

Closed

4 tasks

joshgav added discuss Issues opened for discussions and feedbacks. dont-land-on-v6.x wip Issues and PRs that are still a work in progress. and removed c++ Issues and PRs that require attention from people who are familiar with C++. labels Feb 6, 2017

joyeecheung reviewed Feb 7, 2017

View reviewed changes

joshgav mentioned this pull request Feb 22, 2017

proposal: programmatically expose the V8 inspector URL #11496

Closed

joshgav added the diag-agenda Issues and PRs to discuss during the meetings of the diagnostics working group. label Feb 23, 2017

joshgav mentioned this pull request Feb 23, 2017

Diag WG Meeting - 2017-02 nodejs/diagnostics#85

Closed

joshgav mentioned this pull request Mar 13, 2017

Diag WG Meeting - 2017-03 nodejs/diagnostics#89

Closed

This was referenced Mar 15, 2017

Move V8 inspector to stable #11770

Closed

Switch the CLI debugger to V8 inspector #11421

Closed

gibfahn mentioned this pull request Mar 24, 2017

Disabled or custom UUID for V8 inspector #9185

Closed

joyeecheung mentioned this pull request Mar 27, 2017

Add --auto-open flag w/ --inspect #12069

Closed

joshgav force-pushed the dash-dash-inspect-hint branch from 422f005 to 277ff59 Compare April 5, 2017 17:52

joshgav changed the title ~~[WIP] inspector: hint text update~~ src: update --inspect hint text Apr 5, 2017

MylesBorins mentioned this pull request Apr 5, 2017

Remove Legacy Debugger for 8.0.0 nodejs/CTC#94

Closed

joshgav force-pushed the dash-dash-inspect-hint branch from 5f01c9c to 85ad573 Compare April 19, 2017 13:27

refack mentioned this pull request Apr 23, 2017

regression: 3rd party debuggers are incompatible with node8 nighlies #12364

Closed

Trott mentioned this pull request Apr 24, 2017

Node.js Foundation Core Technical Committee (CTC) Meeting 2017-04-26 nodejs/CTC#111

Closed

segrey mentioned this pull request Apr 26, 2017

Allow to suppress --inspect hint #12665

Closed

joshgav removed ctc-agenda diag-agenda Issues and PRs to discuss during the meetings of the diagnostics working group. labels Apr 26, 2017

joshgav added 2 commits May 3, 2017 10:29

src: update --inspect hint text

1db1a36

* Removes "experimental" warning. * Prints ws://_ip_:_port_:/_uuid_ for all IDs. * Refers to nodejs.org guide for more details. PR-URL: nodejs#11207 Reviewed-By: _tbd_ Reviewed-By: _tbd_

update help URL

5c9335a

joshgav force-pushed the dash-dash-inspect-hint branch from 85ad573 to 5c9335a Compare May 3, 2017 18:08

joshgav mentioned this pull request May 3, 2017

docs: move and update inspector help nodejs/nodejs.org#1216

Closed

joshgav closed this May 4, 2017

joshgav referenced this pull request in nodejs/nodejs.org May 4, 2017

docs: move and update inspector help

13eaf4c

PR-URL: #1216 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jan Krems <jan.krems@gmail.com>

refack mentioned this pull request May 5, 2017

inspector: fix process._debugEnd() for inspector #12777

Merged

3 tasks

jasnell mentioned this pull request May 11, 2017

8.0.0 Release Proposal #12220

Closed

vsemozhetbyt mentioned this pull request Jun 19, 2017

test: debugger/helper-debugger-repl.js is outdated #13779

Closed

LiviaMedeiros mentioned this pull request Aug 10, 2023

https://nodejs.org/en/docs/inspector returns 404 nodejs/nodejs.org#5624

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

src: update --inspect hint text #11207

src: update --inspect hint text #11207

joshgav commented Feb 6, 2017 •

edited

Loading

joyeecheung Feb 7, 2017

cjihrig commented Feb 7, 2017

joshgav commented Feb 7, 2017

mavericken commented Feb 9, 2017 •

edited

Loading

jkrems commented Feb 24, 2017

jkrems commented Apr 3, 2017

joshgav commented Apr 4, 2017

joshgav commented Apr 5, 2017

eugeneo commented Apr 5, 2017

jkrems commented Apr 17, 2017 •

edited

Loading

joshgav commented Apr 19, 2017 •

edited

Loading

joshgav commented Apr 19, 2017

jasnell commented Apr 19, 2017

jkrems commented Apr 19, 2017

Fishrock123 commented Apr 19, 2017

ofrobots commented Apr 19, 2017 •

edited

Loading

Trott commented Apr 19, 2017

mhdawson commented Apr 26, 2017

joshgav commented May 3, 2017

joshgav commented May 4, 2017


		fprintf(out, "\nFor more info go to %s\n\n", GUIDE_URL);

		fprintf(out, MapsToString(this->GetListResponse()).c_str());

src: update --inspect hint text #11207

src: update --inspect hint text #11207

Conversation

joshgav commented Feb 6, 2017 • edited Loading

Checklist

Affected core subsystem(s)

joyeecheung Feb 7, 2017

Choose a reason for hiding this comment

cjihrig commented Feb 7, 2017

joshgav commented Feb 7, 2017

mavericken commented Feb 9, 2017 • edited Loading

jkrems commented Feb 24, 2017

jkrems commented Apr 3, 2017

joshgav commented Apr 4, 2017

joshgav commented Apr 5, 2017

eugeneo commented Apr 5, 2017

jkrems commented Apr 17, 2017 • edited Loading

joshgav commented Apr 19, 2017 • edited Loading

joshgav commented Apr 19, 2017

jasnell commented Apr 19, 2017

jkrems commented Apr 19, 2017

Fishrock123 commented Apr 19, 2017

ofrobots commented Apr 19, 2017 • edited Loading

Trott commented Apr 19, 2017

mhdawson commented Apr 26, 2017

joshgav commented May 3, 2017

joshgav commented May 4, 2017

joshgav commented Feb 6, 2017 •

edited

Loading

mavericken commented Feb 9, 2017 •

edited

Loading

jkrems commented Apr 17, 2017 •

edited

Loading

joshgav commented Apr 19, 2017 •

edited

Loading

ofrobots commented Apr 19, 2017 •

edited

Loading