How to use Node JS debugger with cluster child processes (even for a remote server)

If you are using console.log for debugging Node JS, seriously this post will make your debugging and developing experience a little bit easy.

Node JS provides an easy way to debug an application, all we have to do is add some configurations.

Node JS Debugging on your local machine…

If you want a simple server with a cluster setup for testing purposes, you can clone my repository here.

To start the server use command,

npm run dev

which runs the script command,

node --inspect index.js --port 3000

Here the argument port is optional. Depending upon the CPU cores a respective number of threads will be forked. Now you will see something like this in you CLI,

CLI logs while starting the Node JS server

Now open your chrome browser and open URL chrome://inspect

Click on Configure button

Target discovery settings will pop up, now add the host:port of the Node JS process that we want our debugger to listen on, by default localhost:9222 and localhost:9229 should be present. Otherwise, add them.

Notice that we might have many listeners in the logs i.e. in our example we have from localhost:9229 to localhost:9237, please note that the number of cluster processes might be different for your machine. therefore add all the listeners in the target discovery settings that we just opened in the chrome://inspect -> configure

After adding all the listeners, you will see all the targets in chrome://inspect page, like this

chrome://inspect -> targets

Now open up our server URL and open up the chrome debugger tool. Navigate to http://localhost:3000/ and open up chrome debugger tools (F12 key), here you will see a Node JS green color icon in the first row and next to toggle device toolbar. If you are not seeing the button that means all the threads are not added or the Node JS server is not started with an inspect flag.

Chrome debugger tool button for Node JS

Clicking on it will open up the chrome debugger tool for Node JS application. Like this,

Chrome Debugger for Node JS

Go to Sources -> open up the index.js file (CTRL + p), set a breakpoint inside the route callbacks, example at line number 20 (inside the crypto callback function) and 24 (inside the normal route callback function)

That's it, Navigate to http://localhost:3000/ or http://localhost:3000/performOperation and see the breakpoint being hit in your respective thread (right side in the information panel under Threads tab). For example, in the above image, the thread npm[18008] is hit.

Remote debugging using chrome debugger tools…

For debugging the Node JS process on a remote machine we have to start an SSH tunnel session to forward a port on our local machine over the remote machine port.

To start an SSH tunnel session use the command,

ssh -L <local-port>:localhost:<remote-port> user@remote.example.com

For example ssh -L 9221:localhost:9229 user@remote.example.com or ssh -L 9221:localhost:9229 user@xxx.xxx.xxx.xxx please note that you can use the same local-port and remote-port, the example is just to avoid the confusion.

Since we are trying to debug multiple Node JS threads, we will have to create an SSH tunnel session forwarding for all the port on the server. For example,

ssh -L 9221:localhost:9229 user@xxx.xxx.xxx.xxx

ssh -L 9222:localhost:9230 user@xxx.xxx.xxx.xxx

ssh -L 9223:localhost:9231 user@xxx.xxx.xxx.xxx

After setting up the SSH tunnel, open up the site URL in the chrome browser, open up the chrome debugger tool and open up the Node JS debugger tool. Same as we did for local debugging.

Same as local debug, but this time on remote site URL

Thank you for getting this far. I hope this article proves to be helpful when developing web applications.