feat(v17): Implement tracing channels

[logaretm]

This PR implements tracing channel support as discussed in #4629

The approach ensures that GraphQL has no dependency on the node:diagnostic_channels module in anyway and relies on the consumer of the library to provide it via an enableDiagnosticsChannel API.

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

API

GraphQL will vendor a minimal version of the tracing channel types, ideally i would've liked it to not have any of the deep channel specifics like runStores but it was 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 will 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

The APM provider or the user can do:

import dc from 'node:diagnostic_channels';
import { enableDiagnosticsChannel } from 'graphql';

enableDiagnosticsChannel(dc);

// Then they can subscribe to any of the 5 tracing channels that are available
// usually an APM would 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 (044e252, 3381a40, 46de138, 4855e1e, 6b3f282, 8fcc36f, 90433d1, a13d17d, be6381a, d7491c4, faf327b)

[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.

[Copilot]

This integration test project sets engines.node to >=22, but the main package supports Node 20+. Unless the test relies on Node 22-only diagnostics_channel APIs, consider lowering this to >=20 so the integration test better matches the supported Node range and doesn’t mask compatibility regressions.

Suggested change

	"node": ">=22.0.0"
	"node": ">=20.0.0"

[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.