node-inspector/readme.md

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

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.
• 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:

1. 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
   

2. Send it the USR1 signal

    $ kill -s USR1 2345
   

Great! Now you are ready to attach node-inspector

Debugging

1. start the inspector. I usually put it in the background

    $ node-inspector &
   

2. open http://127.0.0.1:8080/debug?port=5858 in Chrome

3. you should now see the javascript source from node. If you don't, click the scripts tab.

4. select a script and set some breakpoints (far left line numbers)

5. 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

--web-port=[port]     port to host the inspector (default 8080)
--web-host=[host]     host to listen on (default 0.0.0.0)

FAQ / WTF

1. My script runs too fast to attach the debugger.

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

2. I got the ui in a weird state.

when in doubt, refresh

3. 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

Thanks

This project respectfully uses code from and thanks the authors of:

• Blink
• node
• socket.io
• express
• async
• glob