Introduction
To this day I get asked a lot on how I find issues inside my code base, some times even where I put my console.logs(). My answer is that I use a debugger; however almost every time this surprises people in the Node.js/JS community. I thought we had gotten past the strange period of JavaScript as a language where console.log()ing random points in your code base was the way to debug things.
Apparently I was wrong; at least based on how often I get asked this type of thing.
So in the spirit of hoping to propagate something I strongly feel should be a standard and something every JS developer ( or any type of developer really ) should now how to setup and use, this is a small article on how to use Chromes dev tools to debug your Node.js projects.
Installation and Setup For Node 6.3 & Above
In Node 6.3 we got a native debugger module that Node.js now ships with that is actually developed by the Node team. To use this there is now command flag options that we can pass in when starting our node projects. It will do some simple quality of life things as well, if the same file ans instance are brought down and back up the debugger will reattached itself, which is pretty helpful.
Debugging Just Using Node
When you start your application now you just append a --inspect to the node command and it should do everything needed on the process level.
node myProject.js --inspect
Next open up chrome and go to about:inspect in the URL bar. This will bring you to a panel that looks like the image here
You can then click the "Inspect" link under the name and path of your running application and it will open up a standard chrome debugger that is attached to your process.
Debugging using PM2
PM2 is a great process runner that I personally use for all my node related projects. However due to the how PM2 works and handles configurations for projects it requires a little extra work to get running with --inspect.
Managing developer debug configs and app definitions for pm2
A lot of the time you don't want to have create two different files just for debug mode. So what the teams I have been on normally do is just create two application definitions in the same ecosystem.json file and then create different startup commands in our package.json for the devs and startup scripts. You can see the following gist for an example.
Installation and Setup For Node 6.2 & Below
Like most things these days, there is already a package that you can grab that does most of the heavy lifting for you. This package is node-inspector. Install it via the npm command globally via command line :
$ npm i node-inspector -g
Now to ensure that all went well during installation run the inspector command :
$ node-inspector
It should print out a version and a local URL that you can visit.
Hooking up the debugger to your process
Now that the inspector is up and running on your machine you need to hook up your process to it so that it can evaluate the code base as it runs. To accomplish this you will need the process ID of your project after you have started its.
Start your project using something like : node myProject.js
Or if you use PM2 : pm2 start myProject.js
Getting your PID
I normally run my projects through PM2 which gives you the PID in the process table that it prints out; however if you are not doing that you can find your PID by using the ps command as follows :
$ ps -ax | grep node
That should give you a list of all the node instances that are running on your box at the time in which you can pick out the source file that was started ( myProject.js ). Once you have the PID you can then send the PID a signal that tells the process to enable debugging.
Sending the Debug signal to your process
The process of sending the debug signal is very straight forward. I will use $[pid} where your process id that you found earlier should go. Now lets send that signal :
$ kill -s USR1 ${PID}
Now this won't actually kill your process, we are simply sending a system level signal to it, that i what the -s is for in the command. You are now ready to start debugging your running Node.js application.
Getting to your debugger
Getting the node-inspector is as easy as visiting the URL that was print out for you near the beginning of the article with one change. By default V8 starts the debugger on port 5858, if for some reason yours is different, or you have multiple debugging sessions going you can tell node-inspector what port you want to hoot the debugger up to by providing a port as a GET param. For Example
http://127.0.0.1:8080/?port=5858
You can change that port param to whatever your process printed when you sent the system signal.
Wrap up
That's it! Pretty simple, yeah? I hope this is something that people will find useful and we can get away from the console.log() times. Debugging will help save you countless hours, especially when trying to determine what variable is now what value when. You just set a break point and watch it flow to the break point, then you can evaluate the entire state of the application at that moment.
Links
PM2 - https://github.com/Unitech/pm2
Node-Inspector - https://www.npmjs.com/package/node-inspector
Debugger docs - https://nodejs.org/en/docs/inspector/