feat(diagnostics): add enableDiagnosticsChannel and channel registry

Introduces src/diagnostics.ts which exposes a single public function,
enableDiagnosticsChannel(dc), that APMs use to register a
node:diagnostics_channel-compatible module with graphql-js. Channel
names (graphql:parse, graphql:validate, graphql:execute, graphql:resolve,
graphql:subscribe) are owned by graphql-js so multiple APM subscribers
converge on the same cached TracingChannel instances.

Structural MinimalChannel / MinimalTracingChannel / MinimalDiagnosticsChannel
types describe the subset of the Node API graphql-js needs; no dependency
on @types/node is introduced, and no runtime-specific import is added to
the core. Subsequent commits wire emission sites into parse, validate,
execute, subscribe, and the resolver path.

Author: logaretm

src/__tests__/diagnostics-test.ts

@@ -0,0 +1,111 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+
+import { invariant } from '../jsutils/invariant.js';
+
+import type {
+  MinimalDiagnosticsChannel,
+  MinimalTracingChannel,
+} from '../diagnostics.js';
+import { enableDiagnosticsChannel, getChannels } from '../diagnostics.js';
+
+function fakeTracingChannel(name: string): MinimalTracingChannel {
+  const noop: MinimalTracingChannel['start'] = {
+    hasSubscribers: false,
+    publish: () => {
+      /* noop */
+    },
+    runStores: <T>(
+      _ctx: unknown,
+      fn: (this: unknown, ...args: Array<unknown>) => T,
+    ): T => fn(),
+  };
+  const channel: MinimalTracingChannel & { _name: string } = {
+    _name: name,
+    hasSubscribers: false,
+    start: noop,
+    end: noop,
+    asyncStart: noop,
+    asyncEnd: noop,
+    error: noop,
+    traceSync: <T>(fn: (...args: Array<unknown>) => T): T => fn(),
+    tracePromise: <T>(
+      fn: (...args: Array<unknown>) => Promise<T>,
+    ): Promise<T> => fn(),
+  };
+  return channel;
+}
+
+function fakeDc(): MinimalDiagnosticsChannel & {
+  created: Array<string>;
+} {
+  const created: Array<string> = [];
+  const cache = new Map<string, MinimalTracingChannel>();
+  return {
+    created,
+    tracingChannel(name: string) {
+      let existing = cache.get(name);
+      if (existing === undefined) {
+        created.push(name);
+        existing = fakeTracingChannel(name);
+        cache.set(name, existing);
+      }
+      return existing;
+    },
+  };
+}
+
+describe('diagnostics', () => {
+  it('registers the five graphql tracing channels', () => {
+    const dc = fakeDc();
+    enableDiagnosticsChannel(dc);
+
+    expect(dc.created).to.deep.equal([
+      'graphql:execute',
+      'graphql:parse',
+      'graphql:validate',
+      'graphql:resolve',
+      'graphql:subscribe',
+    ]);
+
+    const channels = getChannels();
+    invariant(channels !== undefined);
+    expect(channels.execute).to.not.equal(undefined);
+    expect(channels.parse).to.not.equal(undefined);
+    expect(channels.validate).to.not.equal(undefined);
+    expect(channels.resolve).to.not.equal(undefined);
+    expect(channels.subscribe).to.not.equal(undefined);
+  });
+
+  it('re-registration with the same module preserves channel identity', () => {
+    const dc = fakeDc();
+    enableDiagnosticsChannel(dc);
+    const first = getChannels();
+    invariant(first !== undefined);
+
+    enableDiagnosticsChannel(dc);
+    const second = getChannels();
+    invariant(second !== undefined);
+
+    expect(second.execute).to.equal(first.execute);
+    expect(second.parse).to.equal(first.parse);
+    expect(second.validate).to.equal(first.validate);
+    expect(second.resolve).to.equal(first.resolve);
+    expect(second.subscribe).to.equal(first.subscribe);
+  });
+
+  it('re-registration with a different module replaces stored references', () => {
+    const dc1 = fakeDc();
+    const dc2 = fakeDc();
+
+    enableDiagnosticsChannel(dc1);
+    const first = getChannels();
+    invariant(first !== undefined);
+
+    enableDiagnosticsChannel(dc2);
+    const second = getChannels();
+    invariant(second !== undefined);
+
+    expect(second.execute).to.not.equal(first.execute);
+  });
+});

src/diagnostics.ts

@@ -0,0 +1,127 @@
+/**
+ * TracingChannel integration.
+ *
+ * graphql-js exposes a set of named tracing channels that APM tools can
+ * subscribe to in order to observe parse, validate, execute, subscribe, and
+ * resolver lifecycle events. To preserve the isomorphic invariant of the
+ * core (no runtime-specific imports in `src/`), graphql-js does not import
+ * `node:diagnostics_channel` itself. Instead, APMs (or runtime-specific
+ * adapters) hand in a module satisfying `MinimalDiagnosticsChannel` via
+ * `enableDiagnosticsChannel`.
+ *
+ * Channel names are owned by graphql-js so multiple APMs converge on the
+ * same `TracingChannel` instances and all subscribers coexist.
+ */
+
+/**
+ * Structural subset of `DiagnosticsChannel` sufficient for publishing and
+ * subscriber gating. `node:diagnostics_channel`'s `Channel` satisfies this.
+ */
+export interface MinimalChannel {
+  readonly hasSubscribers: boolean;
+  publish: (message: unknown) => void;
+  runStores: <T, ContextType>(
+    context: ContextType,
+    fn: (this: ContextType, ...args: Array<unknown>) => T,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ) => T;
+}
+
+/**
+ * Structural subset of Node's `TracingChannel`. The `node:diagnostics_channel`
+ * `TracingChannel` satisfies this by duck typing, so graphql-js does not need
+ * a dependency on `@types/node` or on the runtime itself.
+ */
+export interface MinimalTracingChannel {
+  readonly hasSubscribers: boolean;
+  readonly start: MinimalChannel;
+  readonly end: MinimalChannel;
+  readonly asyncStart: MinimalChannel;
+  readonly asyncEnd: MinimalChannel;
+  readonly error: MinimalChannel;
+
+  traceSync: <T>(
+    fn: (...args: Array<unknown>) => T,
+    ctx: object,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ) => T;
+
+  tracePromise: <T>(
+    fn: (...args: Array<unknown>) => Promise<T>,
+    ctx: object,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ) => Promise<T>;
+}
+
+/**
+ * Structural subset of `node:diagnostics_channel` covering just what
+ * graphql-js needs at registration time.
+ */
+export interface MinimalDiagnosticsChannel {
+  tracingChannel: (name: string) => MinimalTracingChannel;
+}
+
+/**
+ * The collection of tracing channels graphql-js emits on. APMs subscribe to
+ * these by name on their own `node:diagnostics_channel` import; both paths
+ * land on the same channel instance because `tracingChannel(name)` is cached
+ * by name.
+ */
+export interface GraphQLChannels {
+  execute: MinimalTracingChannel;
+  parse: MinimalTracingChannel;
+  validate: MinimalTracingChannel;
+  resolve: MinimalTracingChannel;
+  subscribe: MinimalTracingChannel;
+}
+
+let channels: GraphQLChannels | undefined;
+
+/**
+ * Internal accessor used at emission sites. Returns `undefined` when no
+ * `diagnostics_channel` module has been registered, allowing emission sites
+ * to short-circuit on a single property access.
+ *
+ * @internal
+ */
+export function getChannels(): GraphQLChannels | undefined {
+  return channels;
+}
+
+/**
+ * Register a `node:diagnostics_channel`-compatible module with graphql-js.
+ *
+ * After calling this, graphql-js will publish lifecycle events on the
+ * following tracing channels whenever subscribers are present:
+ *
+ *   - `graphql:parse`
+ *   - `graphql:validate`
+ *   - `graphql:execute`
+ *   - `graphql:subscribe`
+ *   - `graphql:resolve`
+ *
+ * Calling this repeatedly is safe: subsequent calls replace the stored
+ * channel references, but since `tracingChannel(name)` is cached by name,
+ * the channel identities remain stable across registrations from the same
+ * underlying module.
+ *
+ * @example
+ * ```ts
+ * import dc from 'node:diagnostics_channel';
+ * import { enableDiagnosticsChannel } from 'graphql';
+ *
+ * enableDiagnosticsChannel(dc);
+ * ```
+ */
+export function enableDiagnosticsChannel(dc: MinimalDiagnosticsChannel): void {
+  channels = {
+    execute: dc.tracingChannel('graphql:execute'),
+    parse: dc.tracingChannel('graphql:parse'),
+    validate: dc.tracingChannel('graphql:validate'),
+    resolve: dc.tracingChannel('graphql:resolve'),
+    subscribe: dc.tracingChannel('graphql:subscribe'),
+  };
+}

src/index.ts

@@ -32,6 +32,17 @@ export { version, versionInfo } from './version.js';
 // Enable development mode for additional checks.
 export { enableDevMode, isDevModeEnabled } from './devMode.js';
 
+// Register a `node:diagnostics_channel`-compatible module to enable
+// tracing channel emission from parse, validate, execute, subscribe,
+// and resolver lifecycles.
+export { enableDiagnosticsChannel } from './diagnostics.js';
+export type {
+  MinimalChannel,
+  MinimalTracingChannel,
+  MinimalDiagnosticsChannel,
+  GraphQLChannels,
+} from './diagnostics.js';
+
 // The primary entry point into fulfilling a GraphQL request.
 export type { GraphQLArgs } from './graphql.js';
 export { graphql, graphqlSync } from './graphql.js';