diff --git a/locale/en/docs/guides/debugging_getting_started.md b/locale/en/docs/guides/debugging_getting_started.md new file mode 100644 index 0000000000000..d5b2fb5689a0a --- /dev/null +++ b/locale/en/docs/guides/debugging_getting_started.md @@ -0,0 +1,173 @@ +--- +title: Debugging - Getting Started +layout: docs.hbs +--- + +# Debugging Guide + +This guide will help you get started debugging your Node.js apps and scripts. + +## Enable Inspector + +**NOTE**: The `--inspect` option and [Inspector Protocol][] are _experimental_ and may change. + +When started with the **--inspect** switch, a Node.js process listens via WebSockets +for diagnostic commands as defined by the [Inspector Protocol][], +by default at host and port 127.0.0.1:9229. Each process is also assigned a +unique [UUID][] (e.g. `0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`). + +Inspector clients must know and specify host address, port, and UUID to connect +to the WebSocket interface. The full URL is +`ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`, of course dependent +on actual host and port and with the correct UUID for the instance. + +Inspector also includes an HTTP endpoint to serve metadata about the debuggee, +including its WebSocket URL, UUID, and Chrome DevTools URL. Get this metadata +by sending an HTTP request to `http://[host:port]/json/list`. This returns a +JSON object like the following; use the `webSocketDebuggerUrl` property as the +URL to connect directly to Inspector. + +```javascript +{ + "description": "node.js instance", + "devtoolsFrontendUrl": "chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e", + "faviconUrl": "https://nodejs.org/static/favicon.ico", + "id": "0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e", + "title": "node", + "type": "node", + "url": "file://", + "webSocketDebuggerUrl": "ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e" +} +``` + +A Node.js process started *without* `--inspect` can also be instructed to start +listening for debugging messages by signaling it with `SIGUSR1` (on Linux and +OS X). As of Node 7 this activates the legacy Debugger API; in Node 8 and later +it will activate the Inspector API. + +--- + +## Inspector Clients + +Several commercial and open source tools can connect to Node's Inspector. Basic +info on these follows: + +#### [node-inspect](https://github.com/nodejs/node-inspect) + +* CLI Debugger supported by the Node.js Foundation which uses the [Inspector Protocol][]. +* A version is bundled with Node and can be used with `node inspect myscript.js`. +* The latest version can also be installed independently (e.g. `npm install -g node-inspect`) + and used with `node-inspect myscript.js`. + +#### [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend) 55+ + +* **Option 1**: Open `chrome://inspect` in a Chromium-based + browser. Click the Configure button and ensure your target host and port + are listed. +* **Option 2**: Copy the `devtoolsFrontendUrl` from the output of `/json/list` + (see above) or the --inspect hint text and paste into Chrome. + +#### [VS Code](https://github.com/microsoft/vscode) 1.10+ + +* In the Debug panel, click the settings icon to open `.vscode/launch.json`. + Select "Node.js" for initial setup. + +#### [JetBrains WebStorm](https://www.jetbrains.com/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. + +#### [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface) + +* Library to ease connections to Inspector Protocol endpoints. + +--- + +## Command-line options + +The following table lists the impact of various runtime flags on debugging: + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning
--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 inspector agent
    • +
  • Listen on port port
    • +
  • Break before user code starts
    • +
+
node inspect script.js +
    +
  • Spawn child process to run user's script under --inspect flag; + and use main process to run CLI debugger.
    • +
+
+ +--- + +## Legacy Debugger + +**The legacy debugger has been deprecated as of Node 7.7.0. Please use --inspect +and Inspector instead.** + +When started with the **--debug** or **--debug-brk** switches in version 7 and +earlier, Node.js listens for debugging commands defined by the discontinued +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 +couple popular ones are listed below. + +The V8 Debugging Protocol is no longer maintained or documented. + +#### [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. + +#### [node-inspector](https://github.com/node-inspector/node-inspector) + +Debug your Node.js app with Chrome DevTools by using an intermediary process +which translates the Inspector Protocol used in Chromium to the V8 Debugger +protocol used in Node.js. + + + +[Inspector Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/ +[UUID]: https://tools.ietf.org/html/rfc4122