feat(v17): Implement tracing channels

[logaretm]

This PR implements tracing channel support as discussed in #4629

graphql-js auto-resolves node:diagnostics_channel at module load via process.getBuiltinModule, with a require fallback for Node 20.0–20.15. On runtimes where node:diagnostics_channel is unavailable (e.g. browsers) the load silently no-ops and emission sites short-circuit. APMs subscribe purely on the subscriber side — no interaction with the graphql API required.

Most of the changes are tests; the actual source changes are mostly tame and introduce wrappers around pre-existing code paths.

API

graphql-js vendors a minimal structural subset of the tracing channel types for internal use. Ideally these wouldn't include deep specifics like runStores, but that surface is required to maintain the sync-or-async behavior we have today. The alternative is to normalize to async for all calls which isn't ideal and probably would have a perf implication.

The implemented channels are:

Channel	Context fields
graphql:parse	source
graphql:validate	schema, document
graphql:execute	schema, document, variableValues, operationName (lazy), operationType (lazy)
graphql:execute	schema, operation, variableValues, operationName, operationType
graphql:subscribe	schema, document, variableValues, operationName (lazy), operationType (lazy)
graphql:resolve	fieldName, parentType, fieldType, args, isTrivialResolver, fieldPath (lazy)

Usage

APMs and users subscribe by channel name on their own node:diagnostics_channel import — no graphql API call needed:

import dc from 'node:diagnostics_channel';

// Subscribe to any of the 5 tracing channels; an APM would typically
// subscribe to all of them.
dc.tracingChannel('graphql:resolve').subscribe({
  start: () => {
    // start a span or log or whatever....
  },
  end: ({ result }) => {
    // if result is present then it is a sync resolve, otherwise they should end the span in asyncEnd
  },
  asyncEnd: ({ result }) => {
    // end the span
  },
  error: ({ error }) => {
    // report resolve errors
  }
});

I tested this locally in a dashboard and it produces waterfall structure like so with basic Sentry integration:

You can view that trace here.

closes #4629

[vercel]

@logaretm is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: logaretm / name: Abdelrahman Awad (03c9fea, 04a3054, 11e890d, 13ccd02, 1d469bb, 23124e5, 2a9d88a, 2e9ebd5, 68d0f57, 82d00ac, 8a1e473, 8a70ca2, 9ad8549, 9efde95, abc84db, acb1945, b84efbd, bbddc0c, d3f2943, ea6e2d5, ec51b09)

[Copilot]

Pull request overview

This PR introduces opt-in diagnostics tracing channels for GraphQL core operations while keeping the codebase runtime-agnostic (no direct node:diagnostics_channel dependency) by requiring consumers to register a compatible module via enableDiagnosticsChannel().

Changes:

• Added src/diagnostics.ts with minimal duck-typed interfaces and maybeTrace* helpers, plus public exports from src/index.ts.
• Wrapped parse, validate, execute/subscribe, and field resolution to emit graphql:* tracing channel lifecycles with lazy context fields where appropriate.
• Added unit tests (via a fake diagnostics channel) and a Node integration test project to validate real node:diagnostics_channel behavior.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/diagnostics.ts	New core diagnostics/tracing channel registration + trace helper implementations.
src/index.ts	Exposes enableDiagnosticsChannel and related public types from the package entrypoint.
src/language/parser.ts	Wraps parse() with tracing emission.
src/validation/validate.ts	Wraps validate() with tracing emission.
src/execution/execute.ts	Wraps execute()/subscribe() and related execution entrypoints with tracing + lazy operation metadata.
src/execution/Executor.ts	Wraps field resolver invocation to emit graphql:resolve lifecycle events with lazy fieldPath.
src/testUtils/fakeDiagnosticsChannel.ts	Adds fake tracing channel implementation to support deterministic unit tests.
src/tests/diagnostics-test.ts	Verifies registration behavior and channel identity semantics.
src/language/tests/parser-diagnostics-test.ts	Validates graphql:parse lifecycle emission.
src/validation/tests/validate-diagnostics-test.ts	Validates graphql:validate lifecycle emission including error paths.
src/execution/tests/execute-diagnostics-test.ts	Validates graphql:execute lifecycle emission for sync/async/error paths.
src/execution/tests/subscribe-diagnostics-test.ts	Validates graphql:subscribe emission for sync vs async subscription setup.
src/execution/tests/resolve-diagnostics-test.ts	Validates graphql:resolve emission for sync/async/error and lazy fieldPath.
resources/integration-test.ts	Adds the new diagnostics integration test project to the integration suite.
integrationTests/diagnostics/test.js	Real Node integration tests for channel lifecycles and ALS propagation.
integrationTests/diagnostics/package.json	Adds diagnostics integration test project metadata and node engine constraint.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[yaacovCR]

is a potential failure mode if this is for some reason called by different APMs with different values?

[logaretm]

As long as it is the actual diagnostic channel module, it will work fine. The failure mode is if one APM provides an implementation and a different one provides another. The diagnostic channel runtime implementations today are idempotent AFAIK so it doesn't matter as long everyone ends up on the same channels.

I think this is a highly specialized case, I initially considered either throwing to force only implementation over the other OR silently NOOP but I that favors whoever comes first which isn't ideal.

WDYT, should this be tweaked?

looping @Qard here as he might have some thoughts here.

[yaacovCR]

We could support multiple diagnostic channels just to avoid this failure mode. Most of the time there would be just one and we would pay the cost of indexing the one item array on every publish, but it seems safest. Thoughts?

in terms of costs in general the introspection query seems to take a 5% hit.

I wonder if that could be reduced if instead of using wrapping functions, we embedded the published decision within the execution code which already tests for sync/async. I guess we would also need some logic to make sure is Publishing/hasSubscribers is uniform

[logaretm]

We could support multiple diagnostic channels just to avoid this failure mode...

Storing two refs means publishing the same event to the same underlying channel twice, which double-fires every subscriber or more depending on how many enableDiagnosticsChannel calls with the same dc module were made.

In server environments it is very unlikely they would resort to anything else other than the diagnostic_channels module available on the runtime because it is already on all these runtimes, yet it is still possible. I think this failure is not worth the added complexity here.

Dedup isn't easy either, import/require would normally resolve the same module, but with mixed cjs/esm cases they would have different references so double fires will happen in that case. A shared global channel is a strength of diag channels, so we should lean on it and trust the users/runtimes do it properly.

We could throw in that case specifically when different dc implementations are detected to make this visible. What do you think?

I wonder if that could be reduced if instead of using wrapping functions, we embedded the published decision within the execution code...

We can try but the issue is runStores will have to wrap everything in the code paths to maintain AsyncLocalStorage store propagation from start->asyncEnd which means either we duplicate a lot of code (traced vs. untraced paths) or take the hit 🤔

[logaretm]

I might've overthinked that last part, pushed 908e1ee to see if it can help. It caches the trace decision on the executor instance and avoids allocating closures if no traced calls are made.

[yaacovCR]

Thanks for checking, I had AI run similar tests but it seems like it used a different module loader or createRequire and they were two different references 🤔 but maybe the test was flawed.

Uh-oh I would be interested in how this could fail? Do you have a way of sharing the failing test code?

[logaretm]

Sure I put it up here:

https://github.com/logaretm/node-dc-identity-repro

[yaacovCR]

That makes sense, and you also point to how we can deduplicate around the identity of dc.tracingChannel, so that seems workable for this hopefully unlikely failure mode.

I would assume import * as dc from 'node:diagnostics_channel would be the same as dc = import('node:diagnostics_channel), both would be covered by checking dc.tracingChannel

[yaacovCR]

Actually, @logaretm on further reflection, because APMs would own the process and instructions for browser bundlers, I think we can use the original mechanism you suggested which implicitly enables directly from node. Apologies for the back and forth.

[logaretm]

No worries, happy to re-work the PR and thanks for discussing it!

[yaacovCR]

The implemented channels are...

Please excuse my limited understanding of the current tracing space, but is there a concept of nesting of channels? In theory, I would expect we would want to:

(1) nest the "execute" channel for subscription events under "subscribe" and
(2) nest "resolve" under "execute"

Naively, I would assume this would be very useful information to understanding the hierarchy.

And I would think this would provide a way to pass the overarching context of the subscribe option to execute (i.e. execute would always have the document, as in your description of the channels/context within the linked issue #4629)?

And similarly, we could also have the overall execute (or subscribe/execute) passed to resolve?

[logaretm]

@yaacovCR Happy to elaborate more!

is there a concept of nesting of channels?

From a purely diag/tracing channels API perspective, there's no parent/child relationship in the API. Each channel is independent. graphql:execute and graphql:resolve don't know about each other at the module level.

That said, the hierarchy you're describing does exist at runtime, it's just reconstructed on the subscriber side rather than on the emitter side. The mechanism is done through AsyncLocalStorage:

You can check the image I had in the PR description that represents how it looks like, or check this trace view as you can see the spans are nested under one another.

This works because tracing channels propagate the async execution context (unlike plain event emitters). Subscribers bind an AsyncLocalStorage to the channel, and every downstream channel fired under that sees the same store via async_hooks. Think of it as an implicit requestId threaded through by the runtime.

It's why I kept the runStores wrapper in the types and impl even after dropping tracePromise. TracingChannel.traceSync/tracePromise wrap runStores for you, but we roll the lifecycle manually here to handle the mixed sync-or-promise return path cleanly, so we need to call runStores ourselves to preserve ALS propagation.

---

Now, for graphql as the emitter, there are a couple of reasons not to encode the hierarchy ourselves:

• GraphQL wouldn't know if the channels are nested, unless we implement logic that does that or use ALS ourselves but that's strictly a node API that's not polyfillable.
• We'd have to track the hierarchy unconditionally even when nothing is subscribed because we don't know at emit time whether a subscriber cares. That defeats the hasSubscribers short-circuit we use on the hot paths today.
• Subscribers can attach to one channel or several or all of them. If graphql baked the hierarchy into the ctx object, we risk breaking it for those partial subs.

The good news is subscribers will have access to document and other parent event objects naturally through their ALS if they want to, graphql doesn't have to do it and subscribers get it for free.

Here is a quick example snippet:

import { AsyncLocalStorage } from 'node:async_hooks';
import dc from 'node:diagnostics_channel';
import { enableDiagnosticsChannel } from 'graphql';

enableDiagnosticsChannel(dc);

const executeCtx = new AsyncLocalStorage();

const executeChannel = dc.tracingChannel('graphql:execute');
const resolveChannel = dc.tracingChannel('graphql:resolve');

// Bind on `start` only, the store activates when execute's runStores frame
// opens and stays active through the entire lifecycle. `end`, `asyncStart`,
// `asyncEnd`, and `error` all fire inside that frame (sync handlers directly,
// async ones via async_hooks propagation), so they inherit the same store
// without any extra wiring.
executeChannel.start.bindStore(executeCtx, ctx => ({
  document: ctx.document,
  operationName: ctx.operationName,
  startedAt: Date.now(),
}));

// Subscribe to the full execute lifecycle. Every handler sees the same store.
executeChannel.subscribe({
  start: () => {
    const { operationName } = executeCtx.getStore();
    console.log(`[execute:start] ${operationName}`);
  },
  end: () => {
    const { operationName, startedAt } = executeCtx.getStore();
    console.log(`[execute:end]   ${operationName} (+${Date.now() - startedAt}ms sync)`);
  },
  asyncStart: () => {
    const { operationName } = executeCtx.getStore();
    console.log(`[execute:asyncStart] ${operationName}`);
  },
  asyncEnd: () => {
    const { operationName, startedAt } = executeCtx.getStore();
    console.log(`[execute:asyncEnd]   ${operationName} (+${Date.now() - startedAt}ms total)`);
  },
  error: ({ error }) => {
    const { operationName } = executeCtx.getStore();
    console.log(`[execute:error] ${operationName} -> ${error.message}`);
  },
});

// Nested channels inherit the parent's store too, because resolve fires
// beneath execute's runStores frame.
resolveChannel.subscribe({
  start: resolveCtx => {
    const parent = executeCtx.getStore();
    console.log(`  [resolve:start] ${resolveCtx.fieldPath} (under ${parent.operationName})`);
  },
  asyncEnd: resolveCtx => {
    const parent = executeCtx.getStore();
    console.log(`  [resolve:asyncEnd] ${resolveCtx.fieldPath} (under ${parent.operationName})`);
  },
  error: ({ error }, name) => {
    const parent = executeCtx.getStore();
    console.log(`  [resolve:error] under ${parent.operationName}: ${error.message}`);
  },
});

[yaacovCR]

@yaacovCR Happy to elaborate more!

This was hugely helpful. On this background, I am wondering whether instead of:

Channel	Context fields
graphql:parse	source
graphql:validate	schema, document
graphql:execute	schema, document, variableValues, operationName (lazy), operationType (lazy)
graphql:subscribe	schema, document, variableValues, operationName (lazy), operationType (lazy)
graphql:resolve	fieldName, parentType, fieldType, args, isTrivialResolver, fieldPath (lazy)

Maybe something like the below would be better for our official tracing channels:

Channel	Context fields
graphql:parse	source
graphql:validate	schema, document
graphql:execute	schema, document, variableValues, operationName (lazy), operationType (lazy)
graphql:executeQueryMutationOrSubscriptionEvent	schema, operation, variableValues, operationName, operationType
graphql:resolve	fieldName, parentType, fieldType, args, isTrivialResolver, fieldPath (lazy)

The idea would be that subscribe is not really "a thing" according to the spec, and in theory our separate execute and subscribe endpoints are just a way to keep track of the relationship between execute and executeSubscriptionEvent. This would nest executeQueryMutationOrSubscriptionEvent under every execute call for queries, mutations, and subscriptions, with one executeQueryMutationOrSubscriptionEvent for each query/mutation execute, and a variable number of executeQueryMutationOrSubscriptionEvent for a subscription execute.

The downside is you can no longer top-level distinguish between subscriptions and queries/mutations. Do we want to preserve that? Do we want to top-level distinguish between each of our operations? What about between queries and mutations?

Again, I am asking these questions with very little knowledge of how the tracing system is used in practice, hopefully you can guide me here?

Looping in @graphql/tsc if they have any thoughts.

[logaretm]

@yaacovCR

Maybe something like the below would be better for our official tracing channels:

We could do graphql:operation as top level and graphql:execute 1x for queries/mutations and N x per sub. Does that track or do we want that lengthy name instead 😅

The downside is you can no longer top-level distinguish between subscriptions and queries/mutations...

The distinction can be done with the args already sent to the execute channel via the operationType property we have right now. Channel level distinction is unlikely to be worth it given how low the overhead is.

I initially added a subscribe channel because it felt like its own thing, but it is better to name channels from GQL's POV, like "I'm doing this thing right here....".

What do u think?

[yaacovCR]

What do u think?

Naming = so hard. Definitely like shorter. But I do prefer consistency with the other verbs we have for our channels.

We could consider:

• execute vs. executeQueryMutationOrSubscriptionEvent (not great if another operation type lands)
• operation vs. execute (not great as operation = noun)
• execute vs. operation (ha! both are not great as it's not clear really which should be the wrapper, although this is incorrect as the nested executeSubscriptionEvent is not an operation, it's more like a sub-operation which is not a thing.)
• executeRequest vs. executeOperation (not correct, a subscription operation does not contain multiple underlying operations, as above)
• executeRequest vs. executeRootSelectionSet (correct and technically disambiguated, as when we execute a single root field to create the source event stream for a subscription, we do not [currently] allow for merging multiple fields by utilizing multiple root fields, so on the subscription side it is [presently] executeSingleAllowedRootField and if we ever change that we could just call that part createSourceEventStream)

I am leaning toward the last option, again looping in better namers @graphql/tsc @graphql/tsc-emeriti

[yaacovCR]

@logaretm

From my machine on 17.x.x I ran:

npm run benchmark -- benchmark/introspectionFromSchema-benchmark.js benchmark/list-sync-benchmark.js benchmark/list-async-benchmark.js benchmark/list-asyncIterable-benchmark.js benchmark/object-async-benchmark.js --revs pr/4670 17.x.x

And got:

1. On our real-world large sync query we got a 7% slowdown. This is the most concerning result.
2. On a synthetic sync query with a lot of list items we got a 23% slowdown, also concerning, although the query is artificial.
3. On synthetic async queries, we were at parity or faster, somehow thanks to this PR and presumably v8 magic!

Not sure if you have any insight. I would assume most of this is secondary to graphql:resolve. Ideally we would of course have no slowdowns at all, at least on these benchmarks when tracing is not enabled.

[logaretm]

@yaacovCR I will re-work the PR to use the autoloading snippet and I will dig into the benchmarks and see what I can do, ideally it should offer close to zero slowdown so I must be doing something wrong.

[yaacovCR]

• executeRequest vs. executeRootSelectionSet (correct and technically disambiguated, as when we execute a single root field to create the source event stream for a subscription, we do not [currently] allow for merging multiple fields by utilizing multiple root fields, so on the subscription side it is [presently] executeSingleAllowedRootField and if we ever change that we could just call that part createSourceEventStream)

I am leaning toward the last option, again looping in better namers @graphql/tsc @graphql/tsc-emeriti

Although maybe we should do instead:
graphql:execute and graphql:execute:rootSelectionSet
or even
graphql:execute and graphql:execute:root-selection-set

is there a convention in the diagnostic channels world?

[logaretm]

@yaacovCR Not a strict convention, but this is what is currently recommended.

For the names, I think we can keep the inner one called graphql:execute for the outer one, how about:

• graphql:request
• graphql:run
• graphql:process
• graphql:handle

Naming is hard 😅

[yaacovCR]

Not necessarily related, but possibly, what would a trace look like for incremental delivery?

Options abound because of the disconnect between execution groups and delivery groups.

[logaretm]

@yaacovCR So I pushed a couple of optimizations, I think it is down significantly after running the benchmark u gave me. It was at 6% overhead at the time of your posting on my machine and now its down to 2.3%-3%.

Can u have a go and see if that's acceptable? I have more ideas but will require juggling alternate Executor class implementations.

---

Not necessarily related, but possibly, what would a trace look like for incremental delivery?

Right now they aren't handled and any deferred executions will be orphaned (up to the APM how to deal with that) since they will still fire the resolve channels.

So it would look like this:

  time ──────────────────────────────────────────────────────►

  execute   ◄────── runStores frame #1 ──────►
  ├─ resolve fieldA        (#2, parented to #1)  ✓
  ├─ resolve fieldB        (#3, parented to #1)  ✓
  └─ returns {initialResult, subsequentResults}
                      ▲ frame #1 ends here ─ generator has not run yet

          ─── gap: framework owns the generator ───

           await subsequentResults.next()   (fresh async context, no ALS)
                                                                       
  resolve fieldC (@defer)  (#4, ⚠ ORPHANED — no parent span)
  resolve fieldD (@stream) (#5, ⚠ ORPHANED — no parent span)

I think we can keep the current PR scoped to this at the moment, and I can try a follow up if this one goes through. I'm thinking we can add another :group channel, so it looks like:

 time ──────────────────────────────────────────────────────►

  execute   ◄────── runStores frame #1 ──────►
  ├─ resolve fieldA        (#2, parented to #1)  ✓
  ├─ resolve fieldB        (#3, parented to #1)  ✓
  └─ returns {initialResult, subsequentResults}
                      ▲ frame #1 ends

          ─── gap: framework drives the generator ───

           await subsequentResults.next()

  execute:group 'slowDefer'  ◄── runStores frame #4 ──►
  └─ resolve fieldC (@defer) (#5, parented to #4)  ✓

  execute:group 'feed@stream' ◄── runStores frame #6 ──►
  └─ resolve fieldD (@stream) (#7, parented to #6)  ✓

The group events look like extra spans, but their real job is to keep an ALS frame alive while the deferred resolvers run, so anything the APM bound stays readable. I'll verify end-to-end in the follow-up

[logaretm]

Squeezed a bit of performance with the last couple of commits 🙌 for the channel names happy to pick whatever works for us here to make this ready to go.