guides: debugging getting started guide #1131

joshgav · 2017-02-06T20:35:58Z

A guide describing the basics of starting Node.js in debug/inspect mode and how to attach any client. Includes a list of popular clients.

A potential goal is to reference this from the hint text when Node.js is started with the --inspect flag, see nodejs/node#8978.

/cc @nodejs/diagnostics @eugeneo

bnoordhuis · 2017-02-06T20:40:38Z

locale/en/docs/guides/debugging_getting_started.md

+to and debug the running process.
+
+A running Node.js process can also be instructed to start listening for
+debugging messages by signaling it with `SIGUSR1` (on Linux and OS X).


Aren't we in the process of deprecating --debug and friends? IIRC, the behavior of SIGUSR1 is going to change, too.

Since this document will appear in the version-independent "Guides" section of the doc, makes sense for it to discuss both --debug and --inspect. But they should be in separate sections I think - inspect first, then debug. You never use both at the same time (I assume!), so having them separated seems right. Each section should also mention which node versions support that type of debug.

If the article would benefit from different content depending on a version, why not include version in the URL of the hint text? ...debugging_getting_started#v7

The main "Guides" article would have no assumptions about the user's version, but if opened from a URL printed by a particular one, some content can be replaced.

Having that option, even if there's only one version that actually benefits from this, might save us some convoluted explanation while being totally optional.

Thanks for the suggestions, I'm going to gather the --debug info in its own section toward the end.

@naugtur: the markdown headers get converted into HTML anchors (fragment identifiers, so it should be possible to refer directly to the --debug section. I'm not going to make the content dynamic based on the fragment here (too much work at the moment), but if you think that would be useful you could start another PR. Thanks!

eugeneo · 2017-02-06T21:31:31Z

LGTM from the Chrome DevTools team. Not sure I should use GitHub "Approve" as there seem to be comments from other parties.

joyeecheung · 2017-02-07T01:22:01Z

locale/en/docs/guides/debugging_getting_started.md

+Metadata about the target debuggee including its UUID can be retrieved via HTTP
+(not websockets) from `http://[host:port]/json/list` with host and port
+properly specified (default: 127.0.0.1:9229). This returns a JSON object like
+the following; use its `webSocketDebuggerUrl` as the connection string including


The last sentence seems to lack something? Who uses that string? (Maybe The debugger client may use..)

That part looks good to me, but

"connection string" is used just once, here, with no prior explanation. ws:.../<UUID> is called "full URL" in the paragraph above.

I suggest:
This returns a JSON object like the one below. Its webSocketDebuggerUrl field is the full URL a debugger needs to connect to the target process because it includes the UUID.

Fixing now. @naugtur thanks for the suggestion, I'm taking out the term "connection string."

joyeecheung · 2017-02-07T01:28:56Z

locale/en/docs/guides/debugging_getting_started.md

+Several commercial and open source tools can connect to Node's
+debugger and/or inspector. Info on these follows.
+
+* [Built-in Debugger](https://github.com/nodejs/node/blob/master/lib/_debugger.js)


I think another way to organize things is:

### Inspector Protocol * node-inspect * Chrome DevTools * VSCode ### Debugger Protocol * Built-in Debugger * Chrome DevTools * VSCode

So people can first look for a client that uses the protocol they prefer(hopefully the inspector protocol) and look for alternatives if their current tool doesn't support the new protocol, but this works fine too.

prigara · 2017-02-07T10:36:47Z

@joshgav we'd like to add info about WebStorm. Should I create a new PR or can you just add it to this PR? Thanks!

WebStorm 2017.1+ and other JetBrains IDEs
Create a new Node.js debug configuration and hit Debug. --inspect will be used by default for Node.js 7+. To disable uncheck js.debugger.node.use.inspect in the IDE Registry.

naugtur · 2017-02-23T18:28:22Z

locale/en/docs/guides/debugging_getting_started.md

+
+Each Node process is marked with its own UUID similar in form to
+`0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`, and debugger clients must specify this
+ID to connect to the debugee. The full URL is


totally ignorable hint: debugee might not be understandable for people less fluent in English. They might think it's yet another tool or component.

must specify this UUID to connect to matching process maybe?

Thank you! I'll find a better term.

I don't suppose there's a one word term other than debugee.

How about:

Each Node process is marked with its own UUID similar in form to
0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e, and debugger clients must specify this
UUID to Indicate which process to connect to.

Note I also changed ID to UUID because ID is an undeclared reference ;)

richardlau · 2017-02-23T21:42:30Z

locale/en/docs/guides/debugging_getting_started.md

+
+## Default ports: 
+
+* Inpsector: 9229


joshgav · 2017-02-24T21:51:50Z

Updated:

Refactored to move legacy --debug info to its own section at the end and focus on Inspector and --inspect.
Added WebStorm info - thanks @prigara!
Updated instructions for some clients and did a general edit pass.

IMO this is ready to land. Could those who previously reviewed please take a look and give a GitHub approval or LGTM? Thank you!

naugtur · 2017-02-24T22:09:37Z

Somehow after you re-arranged it seems much cleaner/shorter. LGTM, even with the debuggee.

PR-URL: #1131 Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Eugene Ostroukhov <eostroukhov@chromium.org>

joshgav · 2017-02-28T00:53:49Z

Landed in b2cdfc8

joshgav mentioned this pull request Feb 6, 2017

inspector,doc: update hint text, add guide nodejs/node#8978

Closed

4 tasks

bnoordhuis reviewed Feb 6, 2017

View reviewed changes

joshgav mentioned this pull request Feb 6, 2017

Updated info on Inspector Protocol (CDP) nodejs/diagnostics#59

Closed

This was referenced Feb 6, 2017

src: update --inspect hint text nodejs/node#11207

Closed

Mention chrome://inspect when using node --inspect nodejs/node#10410

Closed

joyeecheung reviewed Feb 7, 2017

View reviewed changes

This was referenced Feb 16, 2017

Bringing node-inspect into the fold nodejs/diagnostics#67

Closed

Switch the CLI debugger to V8 inspector nodejs/node#11421

Closed

joshgav added the diag-agenda label Feb 23, 2017

joshgav mentioned this pull request Feb 23, 2017

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

Closed

naugtur reviewed Feb 23, 2017

View reviewed changes

richardlau reviewed Feb 23, 2017

View reviewed changes

locale/en/docs/guides/debugging_getting_started.md Outdated

## Default ports:

* Inpsector: 9229

Copy link

Member

richardlau Feb 23, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inspector

joshgav added docs and removed diag-agenda labels Feb 24, 2017

richardlau approved these changes Feb 24, 2017

View reviewed changes

joyeecheung approved these changes Feb 25, 2017

View reviewed changes

guides: debugging getting started guide

b2cdfc8

PR-URL: #1131 Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Eugene Ostroukhov <eostroukhov@chromium.org>

joshgav merged commit b2cdfc8 into nodejs:master Feb 28, 2017

joshgav mentioned this pull request Feb 28, 2017

blog: diag wg update and --debug deprecation #1156

Closed

joyeecheung mentioned this pull request Mar 30, 2017

关于debug的文档？ eggjs/egg#616

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guides: debugging getting started guide #1131

guides: debugging getting started guide #1131

joshgav commented Feb 6, 2017

bnoordhuis Feb 6, 2017

pmuellr Feb 8, 2017

naugtur Feb 23, 2017

joshgav Feb 24, 2017

eugeneo commented Feb 6, 2017

joyeecheung Feb 7, 2017

naugtur Feb 23, 2017 •

edited

Loading

joshgav Feb 24, 2017

joyeecheung Feb 7, 2017

prigara commented Feb 7, 2017

naugtur Feb 23, 2017 •

edited

Loading

joshgav Feb 24, 2017

naugtur Feb 24, 2017

richardlau Feb 23, 2017

joshgav commented Feb 24, 2017

naugtur commented Feb 24, 2017

joshgav commented Feb 28, 2017

guides: debugging getting started guide #1131

guides: debugging getting started guide #1131

Conversation

joshgav commented Feb 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eugeneo commented Feb 6, 2017

Choose a reason for hiding this comment

naugtur Feb 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

prigara commented Feb 7, 2017

naugtur Feb 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshgav commented Feb 24, 2017

naugtur commented Feb 24, 2017

joshgav commented Feb 28, 2017

naugtur Feb 23, 2017 •

edited

Loading

naugtur Feb 23, 2017 •

edited

Loading