feat: Capture thread state from AsyncLocalStorage store

[timfish]

• Ref eventLoopBlockIntegration captures events with missing scope sentry-javascript#17887

This PR retains the original polled state feature so that we still support debug images and session termination on older versions of Node.

For Node.js v24 (and v22 with --experimental-async-context-frame flag) this PR adds support for fetching state from an AsyncLocalStorage instance from the native side. This allows us to fetch the current scopes from the Open Telemetry context object.

With this we will be able to include all scope data and trace context!

import { AsyncLocalStorage } from 'node:async_hooks';
import { Worker } from 'node:worker_threads';
import { registerThread } from '@sentry-internal/node-native-stacktrace';
import { longWork } from './long-work.js';

const asyncLocalStorage = new AsyncLocalStorage();
const SOME_UNIQUE_SYMBOL = Symbol.for('sentry_scopes');

// stateLookup defines the keys required to lookup the context inside the Otel ALS store:
registerThread({ asyncLocalStorage, stateLookup: ['_currentContext', SOME_UNIQUE_SYMBOL] });

function withTraceId(traceId, fn) {
  // This is a decent approximation of how Otel stores context in the ALS store
  return asyncLocalStorage.run({
    _currentContext: new Map([ [SOME_UNIQUE_SYMBOL, { traceId }] ])
  }, fn);
}

const watchdog = new Worker('./test/watchdog.js');

for (let i = 0; i < 10; i++) {
  withTraceId(`trace-${i}`, () => {
    if (i === 5) {
      longWork();
    }
  });
}

Results in the following output:

{
  "0": {
    "frames": [
      {
        "function": "from",
        "filename": "node:buffer",
        "lineno": 304,
        "colno": 28
      },
      {
        "function": "pbkdf2Sync",
        "filename": "node:internal/crypto/pbkdf2",
        "lineno": 79,
        "colno": 17
      },
      {
        "function": "longWork",
        "filename": "/Users/tim/Documents/Repos/node-native-stacktrace/test/long-work.js",
        "lineno": 6,
        "colno": 25
      },
      {
        "function": "?",
        "filename": "file:///Users/tim/Documents/Repos/node-native-stacktrace/test/async-storage.mjs",
        "lineno": 22,
        "colno": 7
      },
    ],
    "asyncState": {
      "traceId": "trace-5"
    }
  }
}

[AbhiPrasad]

@sentry review

[AbhiPrasad]

so this is being accessed in a lock, but it's async right? Will the async operation be safe? Should we just copy the reference to thread_info.async_store?

[timfish]

Unfortunately the v8 objects are mostly not copyable. Here we are passing the reference which is the potentially risky thing.

The lock is held until all the futures have completed so this reference can never be changed from any of our code. This is however just a reference to an object on the javascript heap. Because we hold it as a v8::Global<v8::Value>, this retains a reference which will stop it getting GC'd.

It could go out of scope as the isolate terminates which I've tried to protect against here:
https://github.com/getsentry/sentry-javascript-node-native-stacktrace/pull/24/files#diff-469028a692a3e0cf7037091c4846a3fbd09baf3f789e51d7b4271b5ef911f64bR188

[timfish]

Before we merge this PR I want to see if the changes are sufficient to add scope capture in the @sentry/node-native package!

[timfish]

This has now been tested working with our integration capturing scope!