feat(v17): Implement tracing channels (#4670)

This PR implements tracing channel support for `graphql-js`.

graphql-js resolves `node:diagnostics_channel` at module load through
`process.getBuiltinModule`. On runtimes where the built-in is
unavailable, such as browsers, channel handles are `undefined` and
emission sites short-circuit. APMs subscribe through their own
`node:diagnostics_channel` import by channel name; no GraphQL API call
or option is required.

The implementation adds the diagnostics channel helper, internal
structural typings for the Node tracing-channel surface,
subscriber-facing context types exported from the root package, and
wrappers around parse, validate, execute, subscribe, root-selection-set
execution, variable coercion, and resolver execution. The no-subscriber
path is guarded by `shouldTrace`/`hasSubscribers` checks, with a
sub-channel fallback for runtimes that do not expose aggregate
`TracingChannel.hasSubscribers`. Traced execution uses `runStores` to
preserve tracing-channel async context propagation, does not normalize
synchronous execution to async, and handles promise-like resolver
results without `Promise.resolve` normalization.

Test coverage exercises lifecycle emission, lazy context fields,
no-subscriber no-op behavior, missing `node:diagnostics_channel`
behavior, exported context types, promise-like resolver results, and
runtime compatibility coverage for Bun and Deno.

### API

graphql-js vendors a minimal structural subset of the tracing channel
types for internal use so it does not depend on Node typings or on
`node:diagnostics_channel` being present at runtime. It also exports
subscriber context types from the root package, including
`GraphQLChannelContextByName` and the per-channel context interfaces.

Each channel publishes lifecycle events through Node tracing channels.
The table lists the base context fields present at `start`; successful
sync work adds `result` by `end`, successful async work adds `result` by
`asyncEnd`, and thrown or rejected work adds `error` on the `error`
lifecycle. Variable coercion is synchronous, so it only emits
`start`/`end` and `error` when coercion throws abruptly.

| Channel | Context fields |
|---|---|
| `graphql:parse` | `source` |
| `graphql:validate` | `schema`, `document` |
| `graphql:execute` | `schema`, `document`, `rawVariableValues`,
`operationName` *(lazy)*, `operationType` *(lazy)* |
| `graphql:execute:variableCoercion` | `schema`, `document`,
`operation`, `rawVariableValues`, `operationName`, `operationType` |
| `graphql:execute:rootSelectionSet` | `schema`, `document`,
`operation`, `rawVariableValues`, `operationName`, `operationType` |
| `graphql:subscribe` | `schema`, `document`, `rawVariableValues`,
`operationName` *(lazy)*, `operationType` *(lazy)* |
| `graphql:resolve` | `fieldName`, `alias`, `parentType`, `fieldType`,
`args`, `isDefaultResolver`, `fieldPath` *(lazy)* |

`graphql:execute:variableCoercion` publishes the caller-provided values
as `rawVariableValues`; its successful `result` contains the coerced `{
variableValues }`, or `{ errors }` when coercion returns request errors.

`graphql:execute:rootSelectionSet` fires once for the operation root
selection set. For subscriptions, it fires once per emitted subscription
event, matching the OTel `graphql.subscription.event` shape; subscribers
can distinguish operation kinds through `operationType`.

### Usage

```ts
import dc from 'node:diagnostics_channel';
import type { GraphQLResolveContext } from 'graphql';

dc.tracingChannel('graphql:resolve').subscribe({
  start: (context: GraphQLResolveContext) => {
    // start span
  },
  end: (context: GraphQLResolveContext) => {
    // sync resolver result is available here as context.result
  },
  asyncEnd: (context: GraphQLResolveContext) => {
    // async resolver result is available here as context.result
  },
  error: (context: GraphQLResolveContext) => {
    // report context.error
  },
});
```

Closes #4629

---------

Co-authored-by: Yaacov Rydzinski <yaacovCR@gmail.com>

Author: logaretm

integrationTests/diagnostics-bun/package.json

@@ -0,0 +1,10 @@
+{
+  "description": "graphql-js tracing channels should publish on node:diagnostics_channel (Bun)",
+  "private": true,
+  "scripts": {
+    "test": "docker run --rm --volume \"$PWD\":/usr/src/app -w /usr/src/app oven/bun:\"$BUN_VERSION\"-slim bun test.js"
+  },
+  "dependencies": {
+    "graphql": "file:../graphql.tgz"
+  }
+}

integrationTests/diagnostics-bun/test.js

@@ -0,0 +1,344 @@
+// TracingChannel is marked experimental in Node's docs but is shipped on
+// every runtime graphql-js supports. This test exercises it directly.
+/* eslint-disable n/no-unsupported-features/node-builtins */
+
+import assert from 'node:assert/strict';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import dc from 'node:diagnostics_channel';
+
+import { buildSchema, execute, parse, subscribe, validate } from 'graphql';
+
+function runParseCases() {
+  // graphql:parse - synchronous.
+  {
+    const events = [];
+    const handler = {
+      start: (msg) => events.push({ kind: 'start', source: msg.source }),
+      end: (msg) => events.push({ kind: 'end', source: msg.source }),
+      asyncStart: (msg) =>
+        events.push({ kind: 'asyncStart', source: msg.source }),
+      asyncEnd: (msg) => events.push({ kind: 'asyncEnd', source: msg.source }),
+      error: (msg) =>
+        events.push({ kind: 'error', source: msg.source, error: msg.error }),
+    };
+
+    const channel = dc.tracingChannel('graphql:parse');
+    channel.subscribe(handler);
+
+    try {
+      const doc = parse('{ field }');
+      assert.equal(doc.kind, 'Document');
+      assert.deepEqual(
+        events.map((e) => e.kind),
+        ['start', 'end'],
+      );
+      assert.equal(events[0].source, '{ field }');
+      assert.equal(events[1].source, '{ field }');
+    } finally {
+      channel.unsubscribe(handler);
+    }
+  }
+
+  // graphql:parse - error path fires start, error, end.
+  {
+    const events = [];
+    const handler = {
+      start: (msg) => events.push({ kind: 'start', source: msg.source }),
+      end: (msg) => events.push({ kind: 'end', source: msg.source }),
+      error: (msg) =>
+        events.push({ kind: 'error', source: msg.source, error: msg.error }),
+    };
+
+    const channel = dc.tracingChannel('graphql:parse');
+    channel.subscribe(handler);
+
+    try {
+      assert.throws(() => parse('{ '));
+      assert.deepEqual(
+        events.map((e) => e.kind),
+        ['start', 'error', 'end'],
+      );
+      assert.ok(events[1].error instanceof Error);
+    } finally {
+      channel.unsubscribe(handler);
+    }
+  }
+}
+
+function runValidateCase() {
+  const schema = buildSchema(`type Query { field: String }`);
+  const doc = parse('{ field }');
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        schema: msg.schema,
+        document: msg.document,
+      }),
+    end: () => events.push({ kind: 'end' }),
+    error: (msg) => events.push({ kind: 'error', error: msg.error }),
+  };
+
+  const channel = dc.tracingChannel('graphql:validate');
+  channel.subscribe(handler);
+
+  try {
+    const errors = validate(schema, doc);
+    assert.deepEqual(errors, []);
+    assert.deepEqual(
+      events.map((e) => e.kind),
+      ['start', 'end'],
+    );
+    assert.equal(events[0].schema, schema);
+    assert.equal(events[0].document, doc);
+  } finally {
+    channel.unsubscribe(handler);
+  }
+}
+
+function runExecuteCase() {
+  const schema = buildSchema(`type Query { hello: String }`);
+  const document = parse('query Greeting { hello }');
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        schema: msg.schema,
+        document: msg.document,
+        variableValues: msg.variableValues,
+        operationName: msg.operationName,
+        operationType: msg.operationType,
+      }),
+    end: () => events.push({ kind: 'end' }),
+    asyncStart: () => events.push({ kind: 'asyncStart' }),
+    asyncEnd: () => events.push({ kind: 'asyncEnd' }),
+    error: (msg) => events.push({ kind: 'error', error: msg.error }),
+  };
+
+  const channel = dc.tracingChannel('graphql:execute');
+  channel.subscribe(handler);
+
+  try {
+    const result = execute({
+      schema,
+      document,
+      rootValue: { hello: 'world' },
+    });
+    assert.equal(result.data.hello, 'world');
+    assert.deepEqual(
+      events.map((e) => e.kind),
+      ['start', 'end'],
+    );
+    assert.equal(events[0].operationType, 'query');
+    assert.equal(events[0].operationName, 'Greeting');
+    assert.equal(events[0].document, document);
+    assert.equal(events[0].schema, schema);
+  } finally {
+    channel.unsubscribe(handler);
+  }
+}
+
+function runExecuteRootSelectionSetCase() {
+  const schema = buildSchema(`type Query { hello: String }`);
+  const document = parse('query Greeting { hello }');
+  const operation = document.definitions[0];
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        schema: msg.schema,
+        document: msg.document,
+        operation: msg.operation,
+        variableValues: msg.variableValues,
+        operationName: msg.operationName,
+        operationType: msg.operationType,
+      }),
+    end: (msg) => events.push({ kind: 'end', result: msg.result }),
+    asyncStart: () => events.push({ kind: 'asyncStart' }),
+    asyncEnd: () => events.push({ kind: 'asyncEnd' }),
+    error: (msg) => events.push({ kind: 'error', error: msg.error }),
+  };
+
+  const channel = dc.tracingChannel('graphql:execute:rootSelectionSet');
+  channel.subscribe(handler);
+
+  try {
+    const result = execute({
+      schema,
+      document,
+      rootValue: { hello: 'world' },
+    });
+    assert.equal(result.data.hello, 'world');
+    assert.deepEqual(
+      events.map((e) => e.kind),
+      ['start', 'end'],
+    );
+    assert.equal(events[0].operationType, 'query');
+    assert.equal(events[0].operationName, 'Greeting');
+    assert.equal(events[0].document, document);
+    assert.equal(events[0].operation, operation);
+    assert.equal(events[0].schema, schema);
+    assert.equal(events[1].result, result);
+  } finally {
+    channel.unsubscribe(handler);
+  }
+}
+
+async function runSubscribeCase() {
+  async function* ticks() {
+    yield { tick: 'one' };
+  }
+
+  const schema = buildSchema(`
+    type Query { dummy: String }
+    type Subscription { tick: String }
+  `);
+  // buildSchema doesn't attach a subscribe resolver to fields; inject one.
+  schema.getSubscriptionType().getFields().tick.subscribe = () => ticks();
+
+  const document = parse('subscription Tick { tick }');
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        schema: msg.schema,
+        document: msg.document,
+        variableValues: msg.variableValues,
+        operationName: msg.operationName,
+        operationType: msg.operationType,
+      }),
+    end: () => events.push({ kind: 'end' }),
+    asyncStart: () => events.push({ kind: 'asyncStart' }),
+    asyncEnd: () => events.push({ kind: 'asyncEnd' }),
+    error: (msg) => events.push({ kind: 'error', error: msg.error }),
+  };
+
+  const channel = dc.tracingChannel('graphql:subscribe');
+  channel.subscribe(handler);
+
+  try {
+    const result = subscribe({ schema, document });
+    const stream = typeof result.then === 'function' ? await result : result;
+    if (stream[Symbol.asyncIterator]) {
+      await stream.return?.();
+    }
+    // Subscription setup is synchronous here; start/end fire, no async tail.
+    assert.deepEqual(
+      events.map((e) => e.kind),
+      ['start', 'end'],
+    );
+    assert.equal(events[0].operationType, 'subscription');
+    assert.equal(events[0].operationName, 'Tick');
+  } finally {
+    channel.unsubscribe(handler);
+  }
+}
+
+function runResolveCase() {
+  const schema = buildSchema(
+    `type Query { hello: String nested: Nested } type Nested { leaf: String }`,
+  );
+  const document = parse('{ hello nested { leaf } }');
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        fieldName: msg.fieldName,
+        parentType: msg.parentType,
+        fieldType: msg.fieldType,
+        args: msg.args,
+        isDefaultResolver: msg.isDefaultResolver,
+        fieldPath: msg.fieldPath,
+      }),
+    end: () => events.push({ kind: 'end' }),
+    asyncStart: () => events.push({ kind: 'asyncStart' }),
+    asyncEnd: () => events.push({ kind: 'asyncEnd' }),
+    error: (msg) => events.push({ kind: 'error', error: msg.error }),
+  };
+
+  const channel = dc.tracingChannel('graphql:resolve');
+  channel.subscribe(handler);
+
+  try {
+    const rootValue = { hello: () => 'world', nested: { leaf: 'leaf-value' } };
+    execute({ schema, document, rootValue });
+
+    const starts = events.filter((e) => e.kind === 'start');
+    const paths = starts.map((e) => e.fieldPath);
+    assert.deepEqual(paths, ['hello', 'nested', 'nested.leaf']);
+
+    const hello = starts.find((e) => e.fieldName === 'hello');
+    assert.equal(hello.parentType, 'Query');
+    assert.equal(hello.fieldType, 'String');
+    // buildSchema never attaches field.resolve; all fields report as trivial.
+    assert.equal(hello.isDefaultResolver, true);
+  } finally {
+    channel.unsubscribe(handler);
+  }
+}
+
+function runNoSubscriberCase() {
+  const doc = parse('{ field }');
+  assert.equal(doc.kind, 'Document');
+}
+
+async function runAlsPropagationCase() {
+  // A subscriber that binds a store on the `start` sub-channel should be able
+  // to read it in every lifecycle handler (start, end, asyncStart, asyncEnd).
+  // This is what APMs use to parent child spans to the current operation
+  // without threading state through the context object.
+  const als = new AsyncLocalStorage();
+  const channel = dc.tracingChannel('graphql:execute');
+  channel.start.bindStore(als, (context) => ({
+    operationName: context.operationName,
+  }));
+
+  const seen = {};
+  const handler = {
+    start: () => (seen.start = als.getStore()),
+    end: () => (seen.end = als.getStore()),
+    asyncStart: () => (seen.asyncStart = als.getStore()),
+    asyncEnd: () => (seen.asyncEnd = als.getStore()),
+  };
+  channel.subscribe(handler);
+
+  try {
+    const schema = buildSchema(`type Query { slow: String }`);
+    const document = parse('query Slow { slow }');
+    const rootValue = { slow: () => Promise.resolve('done') };
+
+    await execute({ schema, document, rootValue });
+
+    assert.deepEqual(seen.start, { operationName: 'Slow' });
+    assert.deepEqual(seen.end, { operationName: 'Slow' });
+    assert.deepEqual(seen.asyncStart, { operationName: 'Slow' });
+    assert.deepEqual(seen.asyncEnd, { operationName: 'Slow' });
+  } finally {
+    channel.unsubscribe(handler);
+    channel.start.unbindStore(als);
+  }
+}
+
+async function main() {
+  runParseCases();
+  runValidateCase();
+  runExecuteCase();
+  runExecuteRootSelectionSetCase();
+  await runSubscribeCase();
+  runResolveCase();
+  await runAlsPropagationCase();
+  runNoSubscriberCase();
+  console.log('diagnostics integration test passed');
+}
+
+main();

integrationTests/diagnostics-deno-with-deno-build/deno.json

@@ -0,0 +1,6 @@
+{
+  "imports": {
+    "graphql": "../graphql-deno-dist/index.ts",
+    "graphql/": "../graphql-deno-dist/"
+  }
+}

integrationTests/diagnostics-deno-with-deno-build/package.json

@@ -0,0 +1,7 @@
+{
+  "description": "graphql-js tracing channels should publish on node:diagnostics_channel (Deno with deno build)",
+  "private": true,
+  "scripts": {
+    "test": "docker run --rm --volume \"$PWD/..\":/usr/src/app -w /usr/src/app/diagnostics-deno-with-deno-build denoland/deno:alpine-\"$DENO_VERSION\" deno run test.js"
+  }
+}