337 строки
11 KiB
Markdown
337 строки
11 KiB
Markdown
# Node Inspector
|
|
|
|
[](https://travis-ci.org/node-inspector/node-inspector)
|
|
[](https://gemnasium.com/node-inspector/node-inspector)
|
|
[](http://badge.fury.io/js/node-inspector)
|
|
|
|
|
|
## Overview
|
|
|
|
Node Inspector is a debugger interface for Node.js applications that uses the
|
|
Blink Developer Tools (formerly WebKit Web Inspector).
|
|
|
|
The project maintenance and support is sponsored by
|
|
[StrongLoop](http://strongloop.com).
|
|
|
|
### Table of Content
|
|
|
|
* [Quick Start](#quick-start)
|
|
* [Features](#features)
|
|
* [Known Issues](#known-issues)
|
|
* [Troubleshooting](#troubleshooting)
|
|
* [Advanced Use](#advanced-use)
|
|
* [Configuration](#configuration)
|
|
* [Contributing](#contributing-code)
|
|
* [Credits](#credits)
|
|
|
|
## Quick Start
|
|
|
|
#### Install
|
|
|
|
```sh
|
|
$ npm install -g node-inspector
|
|
```
|
|
|
|
#### Start
|
|
|
|
```sh
|
|
$ node-debug app.js
|
|
```
|
|
|
|
where ```app.js``` is the name of your main Node application JavaScript file.
|
|
|
|
#### Debug
|
|
|
|
The `node-debug` command will load Node Inspector in your default browser.
|
|
|
|
> **NOTE:** Node Inspector works in Chrome and Opera only. You have to re-open
|
|
the inspector page in one of those browsers if another browser
|
|
is your default web browser (e.g. Safari or Internet Explorer).
|
|
|
|
Node Inspector works almost exactly as the Chrome Developer Tools. Read the
|
|
excellent
|
|
[DevTools overview](http://code.google.com/chrome/devtools/docs/scripts.html)
|
|
to get started.
|
|
|
|
Other useful resources:
|
|
- Documentation specific to Node Inspector provided by StrongLoop:
|
|
[Running Node Inspector](http://docs.strongloop.com/display/DOC/Running+Node+Inspector)
|
|
- Miroslav's talk
|
|
[How to Debug Node Apps with Node Inspector](https://vimeo.com/77870960)
|
|
- Danny's [screencasts](http://www.youtube.com/view_play_list?p=A5216AC29A41EFA8)
|
|
(most likely outdated by now)
|
|
- [Getting Started from scratch](http://github.com/node-inspector/node-inspector/wiki/Getting-Started---from-scratch)
|
|
on wiki (most likely outdated by now)
|
|
|
|
## Features
|
|
|
|
The Blink DevTools debugger is a powerful JavaScript debugger interface.
|
|
Node Inspector supports almost all of the debugging features of DevTools, including:
|
|
|
|
* Navigate in your source files
|
|
* Set breakpoints (and specify trigger conditions)
|
|
* Step over, step in, step out, resume (continue)
|
|
* Inspect scopes, variables, object properties
|
|
* Hover your mouse over an expression in your source to display its value in
|
|
a tooltip
|
|
* Edit variables and object properties
|
|
* Continue to location
|
|
* Break on exceptions
|
|
* Disable/enable all breakpoints
|
|
|
|
### Cool stuff
|
|
* Node Inspector uses WebSockets, so no polling for breaks.
|
|
* Remote debugging
|
|
* [Live edit of running code](http://github.com/node-inspector/node-inspector/wiki/LiveEdit),
|
|
optionally persisting changes back to the file-system.
|
|
* Set breakpoints in files that are not loaded into V8 yet - useful for
|
|
debugging module loading/initialization.
|
|
* Javascript from top to bottom :)
|
|
* Embeddable in other applications - see [Embedding HOWTO](docs/embedding.md)
|
|
for more details.
|
|
|
|
## Known Issues
|
|
|
|
* Be careful about viewing the contents of Buffer objects,
|
|
each byte is displayed as an individual array element;
|
|
for most Buffers this will take too long to render.
|
|
* While not stopped at a breakpoint the console doesn't always
|
|
behave as you might expect. See the
|
|
[issue #146](https://github.com/node-inspector/node-inspector/issues/146).
|
|
* Profiler is not implemented yet. Have a look at
|
|
[node-webkit-agent](https://github.com/c4milo/node-webkit-agent)
|
|
in the meantime.
|
|
* Break on uncaught exceptions does not work in all Node versions,
|
|
you need at least v0.11.3 (see
|
|
[node#5713](https://github.com/joyent/node/pull/5713)).
|
|
* Debugging multiple processes (e.g. cluster) is cumbersome.
|
|
Read the following blog post for instructions:
|
|
[Debugging Clustered Apps with Node-Inspector](http://strongloop.com/strongblog/whats-new-nodejs-v0-12-debugging-clusters/)
|
|
|
|
## Troubleshooting
|
|
|
|
#### My script runs too fast to attach the debugger.
|
|
|
|
The debugged process must be started with `--debug-brk`, this way the script is paused on the first line.
|
|
|
|
Note: `node-debug` adds this option for you by default.
|
|
|
|
#### I got the UI in a weird state.
|
|
|
|
When in doubt, refresh the page in browser
|
|
|
|
#### Can I debug remotely?
|
|
|
|
Yes. Node Inspector must be running on the same machine, but your browser can be anywhere.
|
|
Just make sure port 8080 is accessible.
|
|
|
|
#### How do I specify files to hide?
|
|
|
|
Create a JSON-encoded array. You must escape quote characters when using a command-line option.
|
|
|
|
```sh
|
|
$ node-inspector --hidden='["node_modules/framework"]'
|
|
```
|
|
|
|
Note that the array items are interpreted as regular expressions.
|
|
|
|
#### UI doesn't load or doesn't work and refresh didn't help
|
|
|
|
Make sure that you have adblock disabled as well as any other content blocking scripts and plugins.
|
|
|
|
#### How can I (selectively) delete debug session metadata?
|
|
|
|
You may want to delete debug session metadata if for example Node Inspector gets in a bad state with some
|
|
watch variables that were function calls (possibly into some special c-bindings). In such cases, even restarting
|
|
the application/debug session may not fix the problem.
|
|
|
|
Node Inspector stores debug session metadata in the HTML5 local storage.
|
|
You can inspect the contents of local storage and remove any items as
|
|
needed. In Google Chrome, you can execute any of the following in the JavaScript console:
|
|
|
|
```js
|
|
// Remove all
|
|
window.localStorage.clear()
|
|
// Or, to list keys so you can selectively remove them with removeItem()
|
|
window.localStorage
|
|
// Remove all the watch expressions
|
|
window.localStorage.removeItem('watchExpressions')
|
|
// Remove all the breakpoints
|
|
window.localStorage.removeItem('breakpoints')
|
|
```
|
|
|
|
When you are done cleaning up, hit refresh in the browser.
|
|
|
|
#### Node Inspector takes a long time to start up.
|
|
|
|
Try setting --no-preload to true. This option disables searching disk for *.js at startup.
|
|
|
|
#### How do I debug Mocha unit-tests?
|
|
|
|
You have to start `_mocha` as the debugged process and make sure
|
|
the execution pauses on the first line. This way you have enough
|
|
time to set your breakpoints before the tests are run.
|
|
|
|
```sh
|
|
$ node-debug _mocha
|
|
```
|
|
|
|
## Advanced Use
|
|
|
|
While running `node-debug` is a convenient way to start your debugging
|
|
session, there may come time when you need to tweak the default setup.
|
|
|
|
There are three steps needed to get you up and debugging:
|
|
|
|
#### 1. Start the Node Inspector server
|
|
|
|
```sh
|
|
$ node-inspector
|
|
```
|
|
|
|
You can leave the server running in background, it's possible to debug
|
|
multiple processes using the same server instance.
|
|
|
|
#### 2. Enable debug mode in your Node process
|
|
|
|
You can either start Node with a debug flag like:
|
|
|
|
```sh
|
|
$ node --debug your/node/program.js
|
|
```
|
|
|
|
or, to pause your script on the first line:
|
|
|
|
```sh
|
|
$ node --debug-brk your/short/node/script.js
|
|
```
|
|
|
|
Or you can enable debugging on a node that is already running by sending
|
|
it a signal:
|
|
|
|
1. Get the PID of the node process using your favorite method.
|
|
`pgrep` or `ps -ef` are good
|
|
|
|
```sh
|
|
$ pgrep -l node
|
|
2345 node your/node/server.js
|
|
```
|
|
|
|
2. Send it the USR1 signal
|
|
|
|
```sh
|
|
$ kill -s USR1 2345
|
|
```
|
|
|
|
##### Windows
|
|
|
|
Windows does not support UNIX signals. To enable debugging, you can use
|
|
an undocumented API function `process._debugProcess(pid)`:
|
|
|
|
1. Get the PID of the node process using your favorite method, e.g.
|
|
|
|
```sh
|
|
> tasklist /FI "IMAGENAME eq node.exe"
|
|
|
|
Image Name PID Session Name Session# Mem Usage
|
|
========================= ======== ================ =========== ============
|
|
node.exe 3084 Console 1 11,964 K
|
|
```
|
|
|
|
2. Call the API:
|
|
|
|
```sh
|
|
> node -e "process._debugProcess(3084)"
|
|
```
|
|
|
|
#### 3. Load the debugger UI
|
|
|
|
Open http://127.0.0.1:8080/debug?port=5858 in the Chrome browser.
|
|
|
|
## Configuration
|
|
|
|
### node-debug
|
|
|
|
Command line options:
|
|
|
|
```
|
|
--debug-brk, -b Break on the first line (`node --debug-brk`) [default: true]
|
|
--web-port, -p, --port Node Inspector port (`node-inspector --web-port={port}`)
|
|
--debug-port, -d Node/V8 debugger port (`node --debug={port}`)
|
|
--cli, -c CLI mode, do not open browser.
|
|
--version, -v Print Node Inspector's version.
|
|
--help, -h Show this help.
|
|
```
|
|
|
|
### node-inspector
|
|
|
|
node-inspector uses [rc](https://npmjs.org/package/rc)
|
|
[[github]](https://github.com/dominictarr/rc) module to collect options.
|
|
|
|
Places for configuration:
|
|
* command line arguments (parsed by optimist)
|
|
* enviroment variables prefixed with ```node-inspector_```
|
|
* if you passed an option ```--config file``` then from that file
|
|
* a local ```.node-inspectorrc``` or the first found looking in ```./ ../ ../../
|
|
../../../``` etc.
|
|
* ```$HOME/.node-inspectorrc```
|
|
* ```$HOME/.node-inspector/config```
|
|
* ```$HOME/.config/node-inspector```
|
|
* ```$HOME/.config/node-inspector/config```
|
|
* ```/etc/node-inspectorrc```
|
|
* ```/etc/node-inspector/config```
|
|
* options from ```config.json``` for backward compatibility
|
|
* defaults described in Node Inspector`s [./lib/config.js](lib/config.js).
|
|
|
|
All configuration sources that where found will be flattened into one object,
|
|
so that sources earlier in this list override later ones.
|
|
|
|
Use dashed option names in RC files. Sample config file:
|
|
```js
|
|
{
|
|
"web-port": 8088,
|
|
"web-host": null,
|
|
"debug-port": 5858,
|
|
"save-live-edit": true,
|
|
"no-preload": true,
|
|
"hidden": [],
|
|
"stack-trace-limit": 50
|
|
}
|
|
```
|
|
|
|
List of predefined options:
|
|
```
|
|
Option Default Description
|
|
--help | | Print information about options
|
|
--web-port | 8080 | Port to host the inspector
|
|
--web-host | 127.0.0.1 | Host to listen on
|
|
--debug-port | 5858 | Port to connect to the debugging app
|
|
--save-live-edit | false | Save live edit changes to disk
|
|
| | (update the edited files)
|
|
--preload | true | Preload *.js files. You can disable this option
|
|
| | to speed up the startup.
|
|
--hidden | [] | Array of files to hide from the UI
|
|
| | (breakpoints in these files will be ignored)
|
|
--stack-trace-limit | 50 | Number of stack frames to show on a breakpoint
|
|
```
|
|
|
|
## Contributing Code
|
|
|
|
Making Node Inspector the best debugger for node.js cannot be achieved without
|
|
the help of the community. The following resources should help you to get
|
|
started.
|
|
|
|
* [Contributing](https://github.com/node-inspector/node-inspector/wiki/Contributing)
|
|
* [Developer's Guide](https://github.com/node-inspector/node-inspector/wiki/Developer%27s-Guide)
|
|
* [Easy Picks](https://github.com/node-inspector/node-inspector/issues?direction=asc&labels=Easy+Pick&page=1&sort=updated&state=open)
|
|
|
|
## Credits
|
|
|
|
Maintainers
|
|
- [Danny Coates](https://github.com/dannycoates) - the original author
|
|
and a sole maintainer for several years.
|
|
- [Miroslav Bajtoš](https://github.com/bajtos) - the current maintainer,
|
|
sponsored by [StrongLoop](http://strongloop.com).
|
|
|
|
Big thanks to the many contributors to the project, see [AUTHORS](AUTHORS).
|