feat(node): App Not Responding with stack traces

[timfish]

This PR adds ANR detection for Node via a forked child process. The child process runs the same entry point as the main app. To ensure that the main app code does not run in the child process, we use a promise that only resolves in the main process.

When the captureStackTrace option is enabled, debugging is enabled in the main app process and the child process uses WebSockets to capture stack traces via the v8 inspector API.

Overhead is expected to be minimal. With no ANR detected, the only overhead in the main app process is polling the child process over IPC by default every 50ms. The ANR child process consumes around 50-60 MB or RAM and simply keeps track of the polling. Once ANR has been detected, the main process will get paused briefly in the debugger to capture a stack trace frames. At this point, the event loop has been blocked for seconds so the debugging overhead can be considered negligible.

Once an ANR event has been reported, the child process exits to prevent further duplicate events.

import { init, enableANRDetection } from '@sentry/node';

init({ dsn: "__DSN__" });

// ESM supports top-level await
await enableANRDetection({ captureStackTrace: true });
runApp();

// for CJS you'll need then
enableANRDetection({ captureStackTrace: true }).then(() => {
  runApp();
})

It has the following options:

interface Options {
  /**
   * The app entry script. This is used to run the same script as the child process.
   *
   * Defaults to `process.argv[1]`.
   */
  entryScript: string;
  /**
   * Interval to send alive messages to the child process.
   *
   * Defaults to 50ms.
   */
  pollInterval: number;
  /**
   * Threshold in milliseconds to trigger an ANR event.
   *
   * Defaults to 5000ms.
   */
  anrThreshold: number;
  /**
   * Whether to capture a stack trace when the ANR event is triggered.
   *
   * Defaults to `false`.
   *
   * This uses the node debugger which enables the inspector API and opens the required ports.
   */
  captureStackTrace: boolean;
  /**
   * Log debug information.
   */
  debug: boolean;
}

Here is an example event:

[timfish]

The android SDK submits ARN events without handled set, and neither true/false make sense here so I made this optional.

[mydea]

This is really cool! Great work 🎉

[AbhiPrasad]

The promise not resolving in the child process is so clever.

Can we add checks + docstrings for minimum node version?

Not going to merge in just yet, I'm going to bikeshed naming with the team on monday and then we can merge it in after final decision has been made there.

[timfish]

Can we add checks + docstrings for minimum node version?

The CJS test is passing on the Node v10 integration tests and I can't see any reason why I wouldn't also work on v8 too.

I only testing ESM on Node >= v14 since the test was failing for v12. When was top-level await supported from?

[AbhiPrasad]

Top level await is supported for Node 14+, so makes sense for me. Let's make it min required Node 10.

[timfish]

One thing I think this PR doesn't yet cover well enough is handling of unexpected errors. For example if the child process fails to start, we probably want to just log that rather than stop the entire app from starting.