Skip to content

lib: add a diagnostic channel for observing AsyncContextFrame.set #58229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions doc/api/diagnostics_channel.md
Original file line number Diff line number Diff line change
Expand Up @@ -1103,6 +1103,20 @@ for the sync error and one for the async error.

### Built-in Channels

#### Async Context Frame

> Stability: 1 - Experimental

`async_context_frame.set`

* `frame` {Object}

Emitted when the async context frame for the current execution context is set.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this hold true for await?
As far as I remember await or more concrete for Promises the activation/setting happens by v8.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, an event won't be published on await continuation. If we were to implement that, we'd be right back to using Isolate::SetPromiseHook. Fortunately, it is not necessary. V8 appropriately propagates whatever is set as the Continuation Preserved Embedder Data (CPED) into the "then" callbacks. I was a bit vague when saying "native state is kept in sync with change in the active frame" but the idea really is that the derived native state itself should be stored in and retrieved from the AsyncContextFrame (ACF) object, e.g. by defining a private symbol-keyed property on it. This way when V8 changes current ACF as its CPED, the native state automatically tracks and we "only" need to observe when Node sets ACF in CPED for the current execution to ensure the native state in the current ACF object is up to date.
Unsurprisingly, I'm working on doing exactly this in the Datadog's profiler if you want to see a C++ example :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you really interested in the set() calls?
If I understand this correct it's actually the creation of a new AsyncContextFrame - so the ALS.enterWith() and run() calls which are of your interest but not the ACF.exchange() calls.

exchange() is called by e.g. timers, nextTick,... - to mimic what v8 does automatically for promises.

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

> Stability: 1 - Experimental
Expand Down Expand Up @@ -1413,6 +1427,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
Expand Down
4 changes: 4 additions & 0 deletions lib/internal/async_context_frame.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -23,6 +26,7 @@ class ActiveAsyncContextFrame extends SafeMap {

static set(frame) {
setContinuationPreservedEmbedderData(frame);
onSet.publish(frame);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we expose/document the AsyncContextFrame class via public API?
With doing just this users get some undocumented, internal thing into their hand and all they can do is to guess what it is, which API it exposes.
Any internal change on AsyncContextFrame would be breaking for all users of this channel.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I discussed this with @Qard; he thinks (but can of course speak for himself here 😁) that since all channels are by default experimental, we aren't promising stability in what's returned here. As far as I'm concerned, I would've been fine with not even exposing the parameter at all.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the probles to never stabilize async_hooks was because it leaks internal.
We should avoid to add again experimental APIs leaking internal as they can't be stabilized.

If the frame is not needed it's likely best to remove it. Alternative could be to replace it by a well documented wrapper object exposing only parts of AsyncContextFrame or other data like the cause for the set,...

}

static exchange(frame) {
Expand Down
58 changes: 58 additions & 0 deletions test/async-hooks/test-async-local-storage-set-dc.js
Original file line number Diff line number Diff line change
@@ -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);
});
Loading