Debugging Countly servers

Follow

This is a small guide on how to debug Countly servers.

NodeJS version

The minimum supported NodeJS version is 6.3.0.

Requires Chrome

This feature requires the Chrome browser to work.

Since the debugging feature requires node of at least 6.3.0 then this is only possible on Countly version 16.12+.

You might be able to run the debugger on something different than Chrome as long as it has chrome-devtools.

Modify server configuration

The first step is to modify the Countly server supervisord.conf configuration file found in Countly/bin/config/ to support debugging. We need to add the "--inspect" argument to the node server startup command. You can also set the "--debug-brk" argument and the the debugger will stop on the first statement of the server script.

When debugging remotely (NodeJS 8+)

If you need to debug on remote server, you must open outside connections on that port, as well as bind debugger to outside interface by modifying flag to --inspect=123.123.123.123:9229 where 123.123.123.123 is your outside IP address

Please ensure to add these options to the appropriate section (countly-dashboard or countly-api), depending on which application you are looking to debug.

Binding to specific ports (NodeJS 8+)

You can also bind different processes to specific ports, to be able to debug them in parallel. For example, use --inspect=123.123.123.123:9229 for api.js and --inspect=123.123.123.123:5225 for app.js in your supervisord.conf

In this example I am using winscp from windows to change the config files, but you can use whatever tool works best for you.

You should also set that the server uses only 1 worker thread, otherwise the code you want to debug will run in a different thread that you will be inspecting. You should edit the config.js file found in Countly/api/, and add "workers: 1" directive there, as you can see from screenshot below.

After the configuration is set you need to restart the server by calling countly restart.

Running the debugging environment

After you have restarted the server you should open either the error log in the dashboard or open the log file on the server found in "countly/log/countly-api.log". There you should see the url provided for debugging. Use the last one provided every time you restart the server.

The url provided should look similar to "chrome-devtools://devtools/remote/serve_file/@60cd6e859b9f557d2312f5bf532f6aec5f284980/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:5859/8c8a73e5-16b2-4aec-8a51-fee495578558". The next step depends on if the NodeJS server you want to debug is local or remote. If you host the server locally then no changes need to be made. If the server is remote or hosted on a local VM, you should replace "127.0.0.1" with either you servers IP address or domain name.

New debugger link (NodeJS 8+)

New debugger outputs only link where to connect, you need to form link for chrome dev tools yourself. Here is the official documentation on how to achieve that: https://nodejs.org/en/docs/guides/debugging-getting-started/#chrome-devtools-55

You should then paste the resulting string into your chrome or other compatible browser. It should open up on the "Console" tab.

The "Sources" tab should look similar to this:

Improving the workflow

You may have already noticed a small hitchup in the debugging workflow. Every time you make some changes to the backend, you need to restart the server. Every time you restart the server, you get a new debugging url. If you had a remote server then every time you also need to replace the server address. It gets quite tedious and makes the debugging experience worse then it should be.

The solution to this problem is the chrome plugin called "NIM (Node Inspector Manager)"

If you have setup NIM correctly, it should open the correct url every time you restart your node server using "countly restart".

Using the debugging environment

You will soon notice that at first not all .js files are available in the side panel, but after using some endpoint or opening some dashboard pages, they become visible. Those files are loaded dynamically. But once you load them, you can open them in the middle and have them available all the time.

This chrome dev tool works similar to any other debugger. You can put breakpoints, walk through code and view values.

You click on the line numbers to put breakpoints. You can hover your mouse over variables to see their content.

At the top right you can the controls for when you are in the breakpoint. By hovering over you can see their shortcuts. For example F8 for resume, F10 for stepping over and F11 for stepping into statements.

Looking for help?