How to interactively debug Node.js applications on Platform.sh

How-to Guides
, ,
#1

Goal

Interactively debug nodejs applications running on Platform.sh,

Assumptions

  • A Node.js application that is running on Platform.sh
  • An issue that requires interactive debugging, possibly because it can’t be reproduced locally
  • The platform.sh CLI

Problems

Effectively debugging web applications isn’t trivial, especially when an HTTP request goes through multiple layers until it reaches the web app, which is usually the case in cloud platforms.

Debugging in a local environment is easier, but the bug might only trigger when interacting with the data that are present on production.

Steps

The debugging procedure should only be performed on a non-production environment. So, if this is a production issue, first clone the production environment. Platform.sh creates byte-for-byte clones of an environment including the data so there basically is a reproducibility guarantee.

1. Clone production

Using the CLI:

platform branch debug-weird-production-issue master

This will create a new environment debug-weird-production-issue, based on the master branch which is the production environment. It will also checkout the branch locally.

2. Restart the application daemon in debug mode

SSH into this environment with the command:

platform ssh

By default it will connect the current environment branch, in this case debug-weird-production-issue

Stop the running process with the command:

sv stop app

Run the application in debug mode:

node inspect server.js

Note: server.js is the entry point to the application as specified in the platform.app.yaml in the web.start key, so modify this command for the entry point used.

It will output something similar to:

Debugger listening on ws://127.0.0.1:9229/663e3d85-31b0-4f2c-aeb4-94e2fae886cf

Copy the path at the end of the outputted URL (i.e., 663e3d85-31b0-4f2c-aeb4-94e2fae886cf)

3. Forward the debugger port locally

In a second terminal window, create an SSH tunnel that forwards the 9229 port:

ssh -N -L9229:127.0.0.1:9229  $(platform  ssh --pipe)

4. Profit! Chrome Dev tools can be used

Open the Chrome web browser and visit the url:

chrome-devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=127.0.0.1:9229/{path}

Replace {path} with the path that was copied earlier.

For example:

chrome-devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=127.0.0.1:9229/663e3d85-31b0-4f2c-aeb4-94e2fae886cf

Conclusion

Debugging complex bugs that are only reproduced with production data present is non-trivial.

Using a clone of the production data, plus the dynamic nature of Node.js and the fabulous Chrome Dev tools, any bug can be properly investigated.