guides: debugging getting started guide #1131
Conversation
| 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). |
There was a problem hiding this comment.
Aren't we in the process of deprecating --debug and friends? IIRC, the behavior of SIGUSR1 is going to change, too.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!
|
LGTM from the Chrome DevTools team. Not sure I should use GitHub "Approve" as there seem to be comments from other parties. |
| 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 |
There was a problem hiding this comment.
The last sentence seems to lack something? Who uses that string? (Maybe The debugger client may use..)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Fixing now. @naugtur thanks for the suggestion, I'm taking out the term "connection string."
| 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) |
There was a problem hiding this comment.
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.
|
@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 |
|
|
||
| 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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Thank you! I'll find a better term.
There was a problem hiding this comment.
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 ;)
|
|
||
| ## Default ports: | ||
|
|
||
| * Inpsector: 9229 |
|
Updated:
IMO this is ready to land. Could those who previously reviewed please take a look and give a GitHub approval or LGTM? Thank you! |
|
Somehow after you re-arranged it seems much cleaner/shorter. LGTM, even with the debuggee. |
PR-URL: #1131 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Eugene Ostroukhov <[email protected]>
|
Landed in b2cdfc8 |
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
--inspectflag, see nodejs/node#8978./cc @nodejs/diagnostics @eugeneo