1 | # Node Inspector
|
2 |
|
3 | [![Build Status](https://travis-ci.org/node-inspector/node-inspector.svg?branch=master)](https://travis-ci.org/node-inspector/node-inspector)
|
4 | [![NPM version](https://badge.fury.io/js/node-inspector.svg)](http://badge.fury.io/js/node-inspector)
|
5 | [![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=195817)](https://www.bountysource.com/trackers/195817-node-inspector?utm_source=195817&utm_medium=shield&utm_campaign=TRACKER_BADGE)
|
6 |
|
7 | [![Join the chat at https://gitter.im/node-inspector/node-inspector](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/node-inspector/node-inspector?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
8 |
|
9 | ## Overview
|
10 |
|
11 | Node Inspector is a debugger interface for Node.js applications that uses the Blink Developer Tools (formerly WebKit Web Inspector).
|
12 |
|
13 | **Since version 6.3, Node.js provides a built-in DevTools-based debugger which mostly deprecates Node Inspector, see e.g. [this blog post](https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27#.pmqejrn8q) to get started. The built-in debugger is developed directly by the V8/Chromium team and provides certain advanced features (e.g. long/async stack traces) that are too difficult to implement in Node Inspector.**
|
14 |
|
15 |
|
16 | ### Table of Content
|
17 |
|
18 | * [Quick Start](#quick-start)
|
19 | * [Features](#features)
|
20 | * [Known Issues](#known-issues)
|
21 | * [Troubleshooting](#troubleshooting)
|
22 | * [Advanced Use](#advanced-use)
|
23 | * [Configuration](#configuration)
|
24 | * [Contributing](#contributing-code)
|
25 | * [Credits](#credits)
|
26 |
|
27 | ## Quick Start
|
28 |
|
29 | #### Install
|
30 |
|
31 | ```sh
|
32 | $ npm install -g node-inspector
|
33 | ```
|
34 |
|
35 | #### Start
|
36 |
|
37 | ```sh
|
38 | $ node-debug app.js
|
39 | ```
|
40 |
|
41 | where ```app.js``` is the name of your main Node application JavaScript file.
|
42 |
|
43 | See available configuration options [here](https://github.com/node-inspector/node-inspector#configuration)
|
44 |
|
45 | #### Debug
|
46 |
|
47 | The `node-debug` command will load Node Inspector in your default browser.
|
48 |
|
49 | > **NOTE:** Node Inspector works in Chrome and Opera only. You have to re-open
|
50 | the inspector page in one of those browsers if another browser
|
51 | is your default web browser (e.g. Safari or Internet Explorer).
|
52 |
|
53 | Node Inspector works almost exactly as the Chrome Developer Tools. Read the
|
54 | excellent
|
55 | [DevTools overview](https://developer.chrome.com/devtools/index)
|
56 | to get started.
|
57 |
|
58 | Other useful resources:
|
59 | - Documentation specific to Node Inspector provided by StrongLoop:
|
60 | [Debugging with Node Inspector](http://docs.strongloop.com/display/SLC/Debugging+applications)
|
61 | - Miroslav's talk
|
62 | [How to Debug Node Apps with Node Inspector](https://vimeo.com/77870960)
|
63 | - Danny's [screencasts](http://www.youtube.com/view_play_list?p=A5216AC29A41EFA8)
|
64 | (most likely outdated by now)
|
65 | - [Getting Started from scratch](http://github.com/node-inspector/node-inspector/wiki/Getting-Started---from-scratch)
|
66 | on wiki (most likely outdated by now)
|
67 |
|
68 | ## Features
|
69 |
|
70 | The Blink DevTools debugger is a powerful JavaScript debugger interface.
|
71 | Node Inspector supports almost all of the debugging features of DevTools, including:
|
72 |
|
73 | * Navigate in your source files
|
74 | * Set breakpoints (and specify trigger conditions)
|
75 | * Step over, step in, step out, resume (continue)
|
76 | * Inspect scopes, variables, object properties
|
77 | * Hover your mouse over an expression in your source to display its value in
|
78 | a tooltip
|
79 | * Edit variables and object properties
|
80 | * Continue to location
|
81 | * Break on exceptions
|
82 | * Disable/enable all breakpoints
|
83 | * CPU and HEAP profiling
|
84 | * Network client requests inspection
|
85 | * Console output inspection
|
86 |
|
87 | ### Cool stuff
|
88 | * Node Inspector uses WebSockets, so no polling for breaks.
|
89 | * Remote debugging and debugging remote machine.
|
90 | * [Live edit of running code](http://github.com/node-inspector/node-inspector/wiki/LiveEdit),
|
91 | optionally persisting changes back to the file-system.
|
92 | * Set breakpoints in files that are not loaded into V8 yet - useful for
|
93 | debugging module loading/initialization.
|
94 | * Embeddable in other applications - see [Embedding HOWTO](docs/embedding.md)
|
95 | for more details.
|
96 |
|
97 | ## Known Issues
|
98 |
|
99 | * Be careful about viewing the contents of Buffer objects,
|
100 | each byte is displayed as an individual array element;
|
101 | for most Buffers this will take too long to render.
|
102 | * While not stopped at a breakpoint the console doesn't always
|
103 | behave as you might expect. See the
|
104 | [issue #146](https://github.com/node-inspector/node-inspector/issues/146).
|
105 | * Break on uncaught exceptions does not work in all Node versions,
|
106 | you need at least v0.11.3 (see
|
107 | [node#5713](https://github.com/joyent/node/pull/5713)).
|
108 | * Debugging multiple processes (e.g. cluster) is cumbersome.
|
109 | Read the following blog post for instructions:
|
110 | [Debugging Clustered Apps with Node-Inspector](http://strongloop.com/strongblog/whats-new-nodejs-v0-12-debugging-clusters/)
|
111 |
|
112 | ## Troubleshooting
|
113 |
|
114 | #### My script runs too fast to attach the debugger.
|
115 |
|
116 | The debugged process must be started with `--debug-brk`, this way the script is paused on the first line.
|
117 |
|
118 | Note: `node-debug` adds this option for you by default.
|
119 |
|
120 | #### I got the UI in a weird state.
|
121 |
|
122 | When in doubt, refresh the page in browser
|
123 |
|
124 | #### Can I debug remotely?
|
125 |
|
126 | Yes. Node Inspector must be running on the same machine, but your browser can be anywhere.
|
127 | Just make sure port 8080 is accessible.
|
128 |
|
129 | And if Node Inspector is not running on your remote machine, you can also debug it as long as your local machine can connect it.
|
130 | In this way, you must launch Node Inspector with `--no-inject` which means some features are not supported such as profiling and consoling output inspection.
|
131 |
|
132 | So how to debug remote machine with your local Node Inspector?
|
133 |
|
134 | ##### option 1
|
135 | $ node-inspector --debug-host 192.168.0.2 --no-inject
|
136 | then open the url
|
137 | http://127.0.0.1:8080/debug?port=5858
|
138 |
|
139 | ##### option 2
|
140 | $ node-inspector --no-inject
|
141 | then specify the remote machine address as a host parameter in the url
|
142 | e.g.) http://127.0.0.1:8080/debug?host=192.168.123.12&port=5858
|
143 |
|
144 | #### How do I specify files to hide?
|
145 |
|
146 | Create a JSON-encoded array. You must escape quote characters when using a command-line option.
|
147 |
|
148 | ```sh
|
149 | $ node-inspector --hidden='["node_modules/framework"]'
|
150 | ```
|
151 |
|
152 | Note that the array items are interpreted as regular expressions.
|
153 |
|
154 | #### UI doesn't load or doesn't work and refresh didn't help
|
155 |
|
156 | Make sure that you have adblock disabled as well as any other content blocking scripts and plugins.
|
157 |
|
158 | #### How can I (selectively) delete debug session metadata?
|
159 |
|
160 | You may want to delete debug session metadata if for example Node Inspector gets in a bad state with some
|
161 | watch variables that were function calls (possibly into some special c-bindings). In such cases, even restarting
|
162 | the application/debug session may not fix the problem.
|
163 |
|
164 | Node Inspector stores debug session metadata in the HTML5 local storage.
|
165 | You can inspect the contents of local storage and remove any items as
|
166 | needed. In Google Chrome, you can execute any of the following in the JavaScript console:
|
167 |
|
168 | ```js
|
169 | // Remove all
|
170 | window.localStorage.clear()
|
171 | // Or, to list keys so you can selectively remove them with removeItem()
|
172 | window.localStorage
|
173 | // Remove all the watch expressions
|
174 | window.localStorage.removeItem('watchExpressions')
|
175 | // Remove all the breakpoints
|
176 | window.localStorage.removeItem('breakpoints')
|
177 | ```
|
178 |
|
179 | When you are done cleaning up, hit refresh in the browser.
|
180 |
|
181 | #### Node Inspector takes a long time to start up.
|
182 |
|
183 | Try setting --no-preload to true. This option disables searching disk for *.js at startup.
|
184 | Code will still be loaded into Node Inspector at runtime, as modules are required.
|
185 |
|
186 | #### How do I debug Mocha unit-tests?
|
187 |
|
188 | You have to start `_mocha` as the debugged process and make sure
|
189 | the execution pauses on the first line. This way you have enough
|
190 | time to set your breakpoints before the tests are run.
|
191 |
|
192 | ```sh
|
193 | $ node-debug _mocha
|
194 | ```
|
195 |
|
196 | #### How do I debug Gulp tasks?
|
197 |
|
198 | If you are running on a Unix system you can simply run the following command.
|
199 | The `$(which ..)` statement gets replaced with the full path to the gulp-cli.
|
200 |
|
201 | ```sh
|
202 | $ node-debug $(which gulp) task
|
203 | ```
|
204 |
|
205 | If you are running on Windows, you have to get the full path of `gulp.js`
|
206 | to make an equivalent command:
|
207 |
|
208 | ```sh
|
209 | > node-debug %appdata%\npm\node_modules\gulp\bin\gulp.js task
|
210 | ```
|
211 | *You can omit the `task` part to run the `default` task.*
|
212 |
|
213 | ## Advanced Use
|
214 |
|
215 | While running `node-debug` is a convenient way to start your debugging
|
216 | session, there may come time when you need to tweak the default setup.
|
217 |
|
218 | There are three steps needed to get you up and debugging:
|
219 |
|
220 | #### 1. Start the Node Inspector server
|
221 |
|
222 | ```sh
|
223 | $ node-inspector
|
224 | ```
|
225 |
|
226 | You can leave the server running in background, it's possible to debug
|
227 | multiple processes using the same server instance.
|
228 |
|
229 | #### 2. Enable debug mode in your Node process
|
230 |
|
231 | You can either start Node with a debug flag like:
|
232 |
|
233 | ```sh
|
234 | $ node --debug your/node/program.js
|
235 | ```
|
236 |
|
237 | or, to pause your script on the first line:
|
238 |
|
239 | ```sh
|
240 | $ node --debug-brk your/short/node/script.js
|
241 | ```
|
242 |
|
243 | Or you can enable debugging on a node that is already running by sending
|
244 | it a signal:
|
245 |
|
246 | 1. Get the PID of the node process using your favorite method.
|
247 | `pgrep` or `ps -ef` are good
|
248 |
|
249 | ```sh
|
250 | $ pgrep -l node
|
251 | 2345 node your/node/server.js
|
252 | ```
|
253 |
|
254 | 2. Send it the USR1 signal
|
255 |
|
256 | ```sh
|
257 | $ kill -s USR1 2345
|
258 | ```
|
259 |
|
260 | ##### Windows
|
261 |
|
262 | Windows does not support UNIX signals. To enable debugging, you can use
|
263 | an undocumented API function `process._debugProcess(pid)`:
|
264 |
|
265 | 1. Get the PID of the node process using your favorite method, e.g.
|
266 |
|
267 | ```sh
|
268 | > tasklist /FI "IMAGENAME eq node.exe"
|
269 |
|
270 | Image Name PID Session Name Session# Mem Usage
|
271 | ========================= ======== ================ =========== ============
|
272 | node.exe 3084 Console 1 11,964 K
|
273 | ```
|
274 |
|
275 | 2. Call the API:
|
276 |
|
277 | ```sh
|
278 | > node -e "process._debugProcess(3084)"
|
279 | ```
|
280 |
|
281 | #### 3. Load the debugger UI
|
282 |
|
283 | Open http://127.0.0.1:8080/?port=5858 in the Chrome browser.
|
284 |
|
285 | ## Configuration
|
286 |
|
287 | Both `node-inspector` and `node-debug` use [rc](https://npmjs.org/package/rc) module
|
288 | to manage configuration options.
|
289 |
|
290 | Places for configuration:
|
291 | * command line arguments (parsed by [yargs](https://github.com/chevex/yargs))
|
292 | * environment variables prefixed with ```node-inspector_```
|
293 | * if you passed an option ```--config file``` then from that file
|
294 | * a local ```.node-inspectorrc``` or the first found looking in ```./ ../ ../../
|
295 | ../../../``` etc.
|
296 | * ```$HOME/.node-inspectorrc```
|
297 | * ```$HOME/.node-inspector/config```
|
298 | * ```$HOME/.config/node-inspector```
|
299 | * ```$HOME/.config/node-inspector/config```
|
300 | * ```/etc/node-inspectorrc```
|
301 | * ```/etc/node-inspector/config```
|
302 |
|
303 | All configuration sources that where found will be flattened into one object,
|
304 | so that sources earlier in this list override later ones.
|
305 |
|
306 | ### Options
|
307 |
|
308 | | Option | Alias | Default | Description |
|
309 | | :------------------ | :-: | :-----: | :-------- |
|
310 | | **general**
|
311 | | --help | -h | | Display information about available options.<br/>Use `--help -l` to display full usage info.<br/>Use `--help <option>` to display quick help on `option`.
|
312 | | --version | -v | | Display Node Inspector's version.
|
313 | | --debug-port | -d | 5858 | Node/V8 debugger port.<br/>(`node --debug={port}`)
|
314 | | --web-host | | 0.0.0.0 | Host to listen on for Node Inspector's web interface.<br/>`node-debug` listens on `127.0.0.1` by default.
|
315 | | --web-port | -p | 8080 | Port to listen on for Node Inspector's web interface.
|
316 | | **node-debug**
|
317 | | --debug-brk | -b | true | Break on the first line.<br/>(`node --debug-brk`)
|
318 | | --nodejs | | [] | Pass NodeJS options to debugged process.<br/>(`node --option={value}`)
|
319 | | --script | | [] | Pass options to debugged process.<br/>(`node app --option={value}`)
|
320 | | --cli | -c | false | CLI mode, do not open browser.
|
321 | | **node-inspector**
|
322 | | --save-live-edit | | false | Save live edit changes to disk (update the edited files).
|
323 | | --preload | | true | Preload *.js files. You can disable this option<br/>to speed up the startup.
|
324 | | --inject | | true | Enable injection of debugger extensions into the debugged process. It's possible disable only part of injections using subkeys `--no-inject.network`. Allowed keys : `network`, `profiles`, `console`.
|
325 | | --hidden | | [] | Array of files to hide from the UI,<br/>breakpoints in these files will be ignored.<br/>All paths are interpreted as regular expressions.
|
326 | | --stack-trace-limit | | 50 | Number of stack frames to show on a breakpoint.
|
327 | | --ssl-key | | | Path to file containing a valid SSL key.
|
328 | | --ssl-cert | | | Path to file containing a valid SSL certificate.
|
329 |
|
330 | ### Usage examples
|
331 |
|
332 | #### Command line
|
333 | ##### Format
|
334 | ```
|
335 | $ node-debug [general-options] [node-debug-options] [node-inspector-options] [script]
|
336 | ```
|
337 |
|
338 | ```
|
339 | $ node-inspector [general-options] [node-inspector-options]
|
340 | ```
|
341 | ##### Usage
|
342 |
|
343 | Display full usage info:
|
344 | ```
|
345 | $ node-debug --help -l
|
346 | ```
|
347 | Set debug port of debugging process to `5859`:
|
348 | ```
|
349 | $ node-debug -p 5859 app
|
350 | ```
|
351 | Pass `--web-host=127.0.0.2` to node-inspector. Start node-inspector to listen on `127.0.0.2`:
|
352 | ```
|
353 | $ node-debug --web-host 127.0.0.2 app
|
354 | ```
|
355 | Pass `--option=value` to debugging process:
|
356 | ```
|
357 | $ node-debug app --option value
|
358 | ```
|
359 | Start node-inspector to listen on HTTPS:
|
360 | ```
|
361 | $ node-debug --ssl-key ./ssl/key.pem --ssl-cert ./ssl/cert.pem app
|
362 | ```
|
363 | Ignore breakpoints in files stored in `node_modules` folder or ending in `.test.js`:
|
364 | ```
|
365 | $ node-debug --hidden node_modules/ --hidden \.test\.js$ app
|
366 | ```
|
367 | Add `--harmony` flag to the node process running the debugged script:
|
368 | ```
|
369 | $ node-debug --nodejs --harmony app
|
370 | ```
|
371 | Disable preloading of `.js` files:
|
372 | ```
|
373 | $ node-debug --no-preload app
|
374 | ```
|
375 |
|
376 | #### RC Configuration
|
377 |
|
378 | Use dashed option names in RC files. Sample config file (to be saved as `.node-inspectorrc`):
|
379 | ```js
|
380 | {
|
381 | "web-port": 8088,
|
382 | "web-host": "0.0.0.0",
|
383 | "debug-port": 5858,
|
384 | "save-live-edit": true,
|
385 | "preload": false,
|
386 | "hidden": ["\.test\.js$", "node_modules/"],
|
387 | "nodejs": ["--harmony"],
|
388 | "stack-trace-limit": 50,
|
389 | "ssl-key": "./ssl/key.pem",
|
390 | "ssl-cert": "./ssl/cert.pem"
|
391 | }
|
392 | ```
|
393 |
|
394 | ## Contributing Code
|
395 |
|
396 | Making Node Inspector the best debugger for node.js cannot be achieved without
|
397 | the help of the community. The following resources should help you to get
|
398 | started.
|
399 |
|
400 | * [Contributing](https://github.com/node-inspector/node-inspector/wiki/Contributing)
|
401 | * [Developer's Guide](https://github.com/node-inspector/node-inspector/wiki/Developer%27s-Guide)
|
402 | * [Easy Picks](https://github.com/node-inspector/node-inspector/issues?direction=asc&labels=Easy+Pick&page=1&sort=updated&state=open)
|
403 |
|
404 | ## Credits
|
405 |
|
406 | #### Current maintainers
|
407 |
|
408 | - [淘小杰 (hustxiaoc)](https://github.com/hustxiaoc)
|
409 |
|
410 | #### Alumni
|
411 |
|
412 | - [Danny Coates](https://github.com/dannycoates) - the original author and a sole maintainer for several years.
|
413 | - [Miroslav Bajtoš](https://github.com/bajtos) - sponsored by [StrongLoop](http://strongloop.com), maintained Node Inspector through the Node.js 0.10 era.
|
414 | - [3y3](https://github.com/3y3) - maintained Node Inspector in 2015-2016
|
415 |
|
416 | #### Contributors
|
417 |
|
418 |
|
419 | Big thanks to the many contributors to the project, see [Contributors on GitHub](https://github.com/node-inspector/node-inspector/graphs/contributors)
|