Skip to content

Commit b2cdfc8

Browse files
joshgavjoshgav
committed
guides: debugging getting started guide
PR-URL: #1131 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Eugene Ostroukhov <[email protected]>
1 parent 703bacb commit b2cdfc8

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

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

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Debugging - Getting Started
3+
layout: docs.hbs
4+
---
5+
6+
# Debugging Guide
7+
8+
This guide will help you get started debugging your Node.js apps and scripts.
9+
10+
## Enable Inspector
11+
12+
**NOTE**: The `--inspect` option and [Inspector Protocol][] are _experimental_ and may change.
13+
14+
When started with the **--inspect** switch, a Node.js process listens via WebSockets
15+
for diagnostic commands as defined by the [Inspector Protocol][],
16+
by default at host and port 127.0.0.1:9229. Each process is also assigned a
17+
unique [UUID][] (e.g. `0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`).
18+
19+
Inspector clients must know and specify host address, port, and UUID to connect
20+
to the WebSocket interface. The full URL is
21+
`ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e`, of course dependent
22+
on actual host and port and with the correct UUID for the instance.
23+
24+
Inspector also includes an HTTP endpoint to serve metadata about the debuggee,
25+
including its WebSocket URL, UUID, and Chrome DevTools URL. Get this metadata
26+
by sending an HTTP request to `http://[host:port]/json/list`. This returns a
27+
JSON object like the following; use the `webSocketDebuggerUrl` property as the
28+
URL to connect directly to Inspector.
29+
30+
```javascript
31+
{
32+
"description": "node.js instance",
33+
"devtoolsFrontendUrl": "chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e",
34+
"faviconUrl": "https://nodejs.org/static/favicon.ico",
35+
"id": "0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e",
36+
"title": "node",
37+
"type": "node",
38+
"url": "file://",
39+
"webSocketDebuggerUrl": "ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e"
40+
}
41+
```
42+
43+
A Node.js process started *without* `--inspect` can also be instructed to start
44+
listening for debugging messages by signaling it with `SIGUSR1` (on Linux and
45+
OS X). As of Node 7 this activates the legacy Debugger API; in Node 8 and later
46+
it will activate the Inspector API.
47+
48+
---
49+
50+
## Inspector Clients
51+
52+
Several commercial and open source tools can connect to Node's Inspector. Basic
53+
info on these follows:
54+
55+
#### [node-inspect](https://github.com/nodejs/node-inspect)
56+
57+
* CLI Debugger supported by the Node.js Foundation which uses the [Inspector Protocol][].
58+
* A version is bundled with Node and can be used with `node inspect myscript.js`.
59+
* The latest version can also be installed independently (e.g. `npm install -g node-inspect`)
60+
and used with `node-inspect myscript.js`.
61+
62+
#### [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend) 55+
63+
64+
* **Option 1**: Open `chrome://inspect` in a Chromium-based
65+
browser. Click the Configure button and ensure your target host and port
66+
are listed.
67+
* **Option 2**: Copy the `devtoolsFrontendUrl` from the output of `/json/list`
68+
(see above) or the --inspect hint text and paste into Chrome.
69+
70+
#### [VS Code](https://github.com/microsoft/vscode) 1.10+
71+
72+
* In the Debug panel, click the settings icon to open `.vscode/launch.json`.
73+
Select "Node.js" for initial setup.
74+
75+
#### [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) 2017.1+ and other JetBrains IDEs
76+
77+
* Create a new Node.js debug configuration and hit Debug. `--inspect` will be used
78+
by default for Node.js 7+. To disable uncheck `js.debugger.node.use.inspect` in
79+
the IDE Registry.
80+
81+
#### [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
82+
83+
* Library to ease connections to Inspector Protocol endpoints.
84+
85+
---
86+
87+
## Command-line options
88+
89+
The following table lists the impact of various runtime flags on debugging:
90+
91+
<table cellpadding=0 cellspacing=0>
92+
<tr><th>Flag</th><th>Meaning</th></tr>
93+
<tr>
94+
<td>--inspect</td>
95+
<td>
96+
<ul>
97+
<li>Enable inspector agent</li>
98+
<li>Listen on default port (9229)</li>
99+
</ul>
100+
</td>
101+
</tr>
102+
<tr>
103+
<td>--inspect=<i>port</i></td>
104+
<td>
105+
<ul>
106+
<li>Enable inspector agent</li>
107+
<li>Listen on port <i>port</i></li>
108+
</ul>
109+
</td>
110+
</tr>
111+
<tr>
112+
<td>--inspect-brk</td>
113+
<td>
114+
<ul>
115+
<li>Enable inspector agent</li>
116+
<li>Listen on default port (9229)</li>
117+
<li>Break before user code starts</li>
118+
</ul>
119+
</td>
120+
</tr>
121+
<tr>
122+
<td>--inspect-brk=<i>port</i></td>
123+
<td>
124+
<ul>
125+
<li>Enable inspector agent</li>
126+
<li>Listen on port <i>port</i></li>
127+
<li>Break before user code starts</li>
128+
</ul>
129+
</td>
130+
</tr>
131+
<tr>
132+
<td><code>node inspect <i>script.js</i></code></td>
133+
<td>
134+
<ul>
135+
<li>Spawn child process to run user's script under --inspect flag;
136+
and use main process to run CLI debugger.</li>
137+
</ul>
138+
</td>
139+
</tr>
140+
</table>
141+
142+
---
143+
144+
## Legacy Debugger
145+
146+
**The legacy debugger has been deprecated as of Node 7.7.0. Please use --inspect
147+
and Inspector instead.**
148+
149+
When started with the **--debug** or **--debug-brk** switches in version 7 and
150+
earlier, Node.js listens for debugging commands defined by the discontinued
151+
V8 Debugging Protocol on a TCP port, by default `5858`. Any debugger client
152+
which speaks this protocol can connect to and debug the running process; a
153+
couple popular ones are listed below.
154+
155+
The V8 Debugging Protocol is no longer maintained or documented.
156+
157+
#### [Built-in Debugger](https://github.com/nodejs/node/blob/master/lib/_debugger.js)
158+
159+
Start `node debug script_name.js` to start your script under Node's builtin
160+
command-line debugger. Your script starts in another Node process started with
161+
the `--debug-brk` option, and the initial Node process runs the `_debugger.js`
162+
script and connects to your target.
163+
164+
#### [node-inspector](https://github.com/node-inspector/node-inspector)
165+
166+
Debug your Node.js app with Chrome DevTools by using an intermediary process
167+
which translates the Inspector Protocol used in Chromium to the V8 Debugger
168+
protocol used in Node.js.
169+
170+
<!-- refs -->
171+
172+
[Inspector Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
173+
[UUID]: https://tools.ietf.org/html/rfc4122

0 commit comments

Comments
 (0)