lib: add a diagnostic channel for observing AsyncContextFrame.set

doc/api/diagnostics_channel.md

@@ -1109,6 +1109,18 @@ While the diagnostics\_channel API is now considered stable, the built-in
 channels currently available are not. Each channel must be declared stable
 independently.
 
+#### Async Context Frame
+
+`async_context_frame.set`
+
+* `frame` {Object}
+
+Emitted when the async context frame for the current execution context is set.
+This happens in response to [`AsyncLocalStorage.enterWith`][],
+[`AsyncResource.runInAsyncScope`][], and other transitions. Receives the newly
+set internal `AsyncContextFrame` instance. It is not emitted when
+[`--no-async-context-frame`][] is used.
+
 #### Console
 
 `console.log`
@@ -1329,6 +1341,9 @@ Emitted when a new thread is created.
 
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
+[`--no-async-context-frame`]: cli.md#--no-async-context-frame
+[`AsyncLocalStorage.enterWith`]: async_context.md#asynclocalstorageenterwithstore
+[`AsyncResource.runInAsyncScope`]: async_context.md#asyncresourceruninasyncscopefn-thisarg-args
 [`TracingChannel`]: #class-tracingchannel
 [`Worker`]: worker_threads.md#class-worker
 [`asyncEnd` event]: #asyncendevent

lib/internal/async_context_frame.js

@@ -10,6 +10,9 @@ const {
   setContinuationPreservedEmbedderData,
 } = internalBinding('async_context_frame');
 
+const { channel } = require('diagnostics_channel');
+const onSet = channel('async_context_frame.set');
+
 let enabled_;
 
 class ActiveAsyncContextFrame extends SafeMap {
@@ -23,6 +26,7 @@ class ActiveAsyncContextFrame extends SafeMap {
 
   static set(frame) {
     setContinuationPreservedEmbedderData(frame);
+    onSet.publish(frame);
   }
 
   static exchange(frame) {

test/async-hooks/test-async-local-storage-set-dc.js

@@ -0,0 +1,58 @@
+'use strict';
+require('../common');
+
+if (process.execArgv.includes('--no-async-context-frame')) {
+  // Skipping test as it is only relevant when async_context_frame is not disabled.
+  process.exit(0);
+}
+
+const assert = require('assert');
+const { subscribe } = require('diagnostics_channel');
+const { AsyncLocalStorage, AsyncResource } = require('async_hooks');
+
+let frameSetCounter = 0;
+let lastPublishedFrame = 0;
+subscribe('async_context_frame.set', (frame) => {
+  frameSetCounter++;
+  lastPublishedFrame = frame;
+});
+
+const asyncLocalStorage = new AsyncLocalStorage();
+assert.strictEqual(frameSetCounter, 0);
+let lastObservedSetCounter = 0;
+
+function assertFrameWasSet(expectedStore) {
+  assert(frameSetCounter > lastObservedSetCounter);
+  assert.strictEqual(lastPublishedFrame?.get(asyncLocalStorage), expectedStore);
+  lastObservedSetCounter = frameSetCounter;
+}
+
+setImmediate(() => {
+  // Entering an immediate callback sets the frame.
+  assertFrameWasSet(undefined);
+  const store = { foo: 'bar' };
+  asyncLocalStorage.enterWith(store);
+  // enterWith sets the frame.
+  assertFrameWasSet(store);
+  assert.strictEqual(asyncLocalStorage.getStore(), store);
+
+  setTimeout(() => {
+    // Entering a timeout callback sets the frame.
+    assertFrameWasSet(store);
+    assert.strictEqual(asyncLocalStorage.getStore(), store);
+    const res = new AsyncResource('test');
+    const store2 = { foo: 'bar2' };
+    asyncLocalStorage.enterWith(store2);
+    // enterWith sets the frame.
+    assertFrameWasSet(store2);
+    res.runInAsyncScope(() => {
+      // runInAsyncScope sets the frame on entry.
+      assertFrameWasSet(store);
+      // AsyncResource was constructed before store2 assignment, so it should
+      // keep reflecting the old store.
+      assert.strictEqual(asyncLocalStorage.getStore(), store);
+    });
+    // runInAsyncScope sets the frame on exit.
+    assertFrameWasSet(store2);
+  }, 10);
+});