Node Inspector

Overview

Node Inspector is a debugger interface for node.js using the Blink Developer Tools (former WebKit Web Inspector).

Features

The Blink DevTools debugger is a great javascript debugger interface; it works just as well for node. Node Inspector supports almost all of the debugging features of DevTools.

Navigate in your source files
Set breakpoints (and specify trigger conditions)
Break on exceptions
Step over, step in, step out, resume (continue)
Continue to location
Disable/enable all breakpoints
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
(etc.)

Cool stuff

Node Inspector uses WebSockets, so no polling for breaks.
Remote debugging
Live edit of running code, 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 for more details.

Known Issues

This is beta-quality code, so use at your own risk.

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 issue #146.
Profiler is not implemented yet. Have a look at node-webkit-agent in the meantime.
Break on uncaught exceptions does not work because of missing support in node.
Debugging multiple processes (e.g. cluster) is cumbersome.

Getting Started

Requirements

node.js
- version 0.8 or later
npm
A Blink-based browser (i.e. Google Chrome)

Install

With npm
```
  $ npm install -g node-inspector
```

Enable debug mode

To use node-inspector, enable debugging on the node you wish to debug. You can either start node with a debug flag like:

$ node --debug your/node/program.js

or, to pause your script on the first line:

$ 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:

Get the PID of the node process using your favorite method. pgrep or ps -ef are good
```
 $ pgrep -l node
 2345 node your/node/server.js
```
Send it the USR1 signal
```
 $ kill -s USR1 2345
```

Great! Now you are ready to attach node-inspector.

Windows

Windows does not support UNIX signals. To enable debugging, you can use an undocumented API function process._debugProcess(pid):

Get the PID of the node process using your favorite method, e.g.

> tasklist /FI "IMAGENAME eq node.exe"

Image Name                     PID Session Name        Session#    Mem Usage
========================= ======== ================ =========== ============
node.exe                      3084 Console                    1     11,964 K

Call the API:
```
> node -e "process._debugProcess(3084)"
```

Great! Now you are ready to attach the inspector.

Debugging

start the inspector. I usually put it in the background
```
 $ node-inspector &
```
open http://127.0.0.1:8080/debug?port=5858 in Chrome
you should now see the javascript source from node. If you don't, click the scripts tab.
select a script and set some breakpoints (far left line numbers)
then watch the screencasts

For more information on getting started see the wiki

node-inspector works almost exactly like the web inspector in Chrome. Here's a good overview of the UI

Inspector options

Node-inspector uses rc [github] 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.

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:

{
  "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)
    --no-preload         |    false    | Disables preloading *.js to speed up 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

FAQ / WTF

My script runs too fast to attach the debugger.

use --debug-brk to pause the script on the first line

I got the ui in a weird state.

when in doubt, refresh

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 to specify list of files to hide?

Create a JSON-encoded array, don't forget to escape the quote characters when using a command-line option.
$ 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.

I got my Node Inspector instance in a bad state with some watch variables that were function calls (possibly into some special c-bindings) and restart of the application/debug session did not fix the problem. How can I (selectively) delete debug session metadata?

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:

// 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. Disables searching disk for *.js at startup.

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.

Thanks

Danny Coates for starting the project and maintaining it for several years.

StrongLoop for upgrading to the Blink front-end and maintaining the project onwards.

And of course all developers that contributed patches and features, as listed in the AUTHORS file.

lukas-shawford / node-inspector