From a5932b228361281347218e7fd0ad02361eb6e365 Mon Sep 17 00:00:00 2001 From: Josh Gavant Date: Wed, 3 Aug 2016 14:28:47 -0700 Subject: [PATCH 1/3] inspector,doc: update hint text, add guide Updates hint text for --inspect to be more generic. Instructions for various debugger clients moved into a referenced guide. PR-URL: https://github.com/nodejs/node/pull/8978 Fixes: https://github.com/nodejs/node/pull/7182 Reviewed-By: Reviewed-By: --- doc/guides/debugging.md | 176 +++++++++++++++++++++++++++++ src/inspector_agent.cc | 13 +-- test/inspector/inspector-helper.js | 18 ++- 3 files changed, 194 insertions(+), 13 deletions(-) create mode 100644 doc/guides/debugging.md diff --git a/doc/guides/debugging.md b/doc/guides/debugging.md new file mode 100644 index 00000000000000..fe01dcc5d7d1a5 --- /dev/null +++ b/doc/guides/debugging.md @@ -0,0 +1,176 @@ +# Debugging Guide + + + +The goal of this guide is to provide you with enough information to get started +debugging your Node.js apps and scripts. + +## Enable Debugging + +When started with the **--debug** or **--debug-brk** switches, Node.js listens +for debugging commands defined by the [V8 Debugging Protocol][] on a TCP port, +by default `5858`. Any debugger client which speaks this protocol can connect +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). + +When started with the **--inspect** or **--inspect-brk** switches, Node.js +listens for diagnostic commands defined by the [Chrome Debugging Protocol][] +via websockets, by default at `ws://127.0.0.1:9229/node`. Any diagnostics +client which speaks this protocol can connect to and debug the running process. + +The `--inspect` option and protocol are _experimental_ and may change. + +[V8 Debugging Protocol]: https://github.com/v8/v8/wiki/Debugging-Protocol +[Chrome Debugging Protocol]: https://developer.chrome.com/devtools/docs/debugger-protocol + + +## Debugging Clients + +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) + + * Start `node debug script_name.js` to start your script under Node's + builtin command-line debugger. Your script starts in another Node + process started with the `--debug-brk` option, and the initial Node + process runs the `_debugger.js` script and connects to your target. + +* [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend) + + * **Option 1 (Chrome 55+)**: Open `chrome://inspect` in your Chromium + browser. Click the Configure button and ensure your target host and port + are listed. + * **Option 2**: Paste the following URL in Chrome, + replacing the `ws` parameter with your hostname and port as needed: + + `chrome-devtools://devtools/remote/serve_file/@60cd6e859b9f557d2312f5bf532f6aec5f284980/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node` + + > The hash represents the current revision and is specified in + + +* [VS Code](https://github.com/microsoft/vscode) + * **Option 1**: In the Debug panel, click the settings button to choose + initial debug configurations. Select "Node.js v6.3+ (Experimental)" for + `--inspect` support, or "Node.js" for `--debug` support. + * **Option 2**: In debug configurations in `.vscode/launch.json`, set `type` + as `node2`. + + * For more info, see . + +* [IntelliJ WebStorm](tbd) + +* [node-inspector](https://github.com/node-inspector/node-inspector) + +* [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface) + + +## Debugging command-line options + +* The following table clarifies the implications of various diag-related flags: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning
--debug +
    +
  • Enable debugger agent
  • +
  • Listen on default port (5858)
  • +
+
--debug=port +
    +
  • Enable debugger agent
  • +
  • Listen on port port
  • +
+
--debug-brk +
    +
  • Enable debugger agent
  • +
  • Listen on default port (5858)
  • +
  • Break before user code starts
  • +
+
--debug-brk=port +
    +
  • Enable debugger agent
  • +
  • Listen on port port
  • +
  • Break before user code starts
  • +
+
--inspect +
    +
  • Enable inspector agent
  • +
  • Listen on default port (9229)
  • +
+
--inspect=port +
    +
  • Enable inspector agent
  • +
  • Listen on port port
  • +
+
--inspect-brk +
    +
  • Enable inspector agent
  • +
  • Listen on default port (9229)
  • +
  • Break before user code starts
  • +
+
--inspect-brk=port +
    +
  • Enable debugger agent
  • +
  • Listen on port port
  • +
  • Break before user code starts
  • +
+
--debug-port=port +
    +
  • Set port to port for other flags. Must come after others. +
+
node debug script.js +
    +
  • Spawn child process to run user script under --debug mode, + and use main process to run CLI debugger.
  • +
+
+ + +## Default ports: + +* Inpsector: 9229 +* Debugger: 5858 + diff --git a/src/inspector_agent.cc b/src/inspector_agent.cc index aec0bc06e32334..643c04992fdf28 100644 --- a/src/inspector_agent.cc +++ b/src/inspector_agent.cc @@ -43,13 +43,12 @@ std::string GetWsUrl(int port, const std::string& id) { } void PrintDebuggerReadyMessage(int port, const std::string& id) { - fprintf(stderr, "Debugger listening on port %d.\n" - "Warning: This is an experimental feature and could change at any time.\n" - "To start debugging, open the following URL in Chrome:\n" - " chrome-devtools://devtools/remote/serve_file/" - "@" V8_INSPECTOR_REVISION "/inspector.html?" - "experiments=true&v8only=true&ws=%s\n", - port, GetWsUrl(port, id).c_str()); + fprintf(stderr, "Debugger listening on \x1B[33mws://%s\x1b[0m\n" + "* Info on connecting at" + "\x1B[33mhttps://nodejs.org/en/docs/guides/debugging\x1B[0m.\n" + "* Warning: This is an experimental feature and could change at any time." + "\n\n", + GetWsUrl(port, id).c_str()); fflush(stderr); } diff --git a/test/inspector/inspector-helper.js b/test/inspector/inspector-helper.js index 850df8718fbe7c..7920d11d31cf0b 100644 --- a/test/inspector/inspector-helper.js +++ b/test/inspector/inspector-helper.js @@ -412,20 +412,26 @@ exports.startNodeForInspectorTest = function(callback) { const timeoutId = timeout('Child process did not start properly', 4); - let found = false; + var found = false; const dataCallback = makeBufferingDataCallback((text) => { clearTimeout(timeoutId); console.log('[err]', text); if (found) return; - const match = text.match(/Debugger listening on port (\d+)/); - found = true; - child.stderr.removeListener('data', dataCallback); - assert.ok(match, text); - callback(new Harness(match[1], child)); + const re = /Debugger listening on.*ws:\/\/(.*):(\d+)\/(\w+)/; + const match = text.match(re); + if (match) { + found = true; + child.stderr.removeListener('data', dataCallback); + callback(new Harness(match[2], child)); + return; + } }); child.stderr.on('data', dataCallback); + child.on('exit', (code, signal) => { + assert.ok(found, 'Failed to start child script.'); + }); const handler = tearDown.bind(null, child); From 0d45247b0259893f4d166e389ef335c98d0b21e7 Mon Sep 17 00:00:00 2001 From: Josh Gavant Date: Fri, 14 Oct 2016 10:05:14 -0700 Subject: [PATCH 2/3] squash: add webstorm instructions --- doc/guides/debugging.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/guides/debugging.md b/doc/guides/debugging.md index fe01dcc5d7d1a5..7392f174285a15 100644 --- a/doc/guides/debugging.md +++ b/doc/guides/debugging.md @@ -60,7 +60,10 @@ debugger and/or inspector. Info on these follows. * For more info, see . -* [IntelliJ WebStorm](tbd) +* [WebStorm](https://www.jetbrains.com/webstorm/) 2016.2+ and other JetBrains + IDEs (IJ U, PS, PC, RM, CL, AC) + * In the Node.js debug configuration add `--inspect` to the Node parameters + field for `--inspect` support. By default, the debug process will use V8 Debugging Protocol. * [node-inspector](https://github.com/node-inspector/node-inspector) @@ -171,6 +174,6 @@ debugger and/or inspector. Info on these follows. ## Default ports: -* Inpsector: 9229 +* Inspector: 9229 * Debugger: 5858 From b0d785cc28e98076ef6cf95b0c30c495bf92261d Mon Sep 17 00:00:00 2001 From: Josh Gavant Date: Fri, 14 Oct 2016 10:07:20 -0700 Subject: [PATCH 3/3] squash: update chrome-devtools URL --- doc/guides/debugging.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/guides/debugging.md b/doc/guides/debugging.md index 7392f174285a15..07afd7a144301e 100644 --- a/doc/guides/debugging.md +++ b/doc/guides/debugging.md @@ -46,10 +46,7 @@ debugger and/or inspector. Info on these follows. * **Option 2**: Paste the following URL in Chrome, replacing the `ws` parameter with your hostname and port as needed: - `chrome-devtools://devtools/remote/serve_file/@60cd6e859b9f557d2312f5bf532f6aec5f284980/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node` - - > The hash represents the current revision and is specified in - + `chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node` * [VS Code](https://github.com/microsoft/vscode) * **Option 1**: In the Debug panel, click the settings button to choose @@ -63,7 +60,8 @@ debugger and/or inspector. Info on these follows. * [WebStorm](https://www.jetbrains.com/webstorm/) 2016.2+ and other JetBrains IDEs (IJ U, PS, PC, RM, CL, AC) * In the Node.js debug configuration add `--inspect` to the Node parameters - field for `--inspect` support. By default, the debug process will use V8 Debugging Protocol. + field for `--inspect` support. By default, the debug process will use V8 + Debugging Protocol. * [node-inspector](https://github.com/node-inspector/node-inspector)