feat(language): publish on graphql:parse tracing channel

Wraps parse() with the graphql:parse channel when any subscribers are
attached. The published context carries the Source (or string) handed to
parse() so APM tools can record the GraphQL source on their span.

Adds two shared helpers on src/diagnostics.ts used by every subsequent
emission site:

  maybeTraceSync(name, ctxFactory, fn)
  maybeTracePromise(name, ctxFactory, fn)

They share a shouldTrace gate that uses hasSubscribers !== false so
runtimes without an aggregated hasSubscribers getter (notably Node 18,
see nodejs/node#54470) still publish; Node's traceSync/tracePromise gate
each sub-channel internally. Context construction is lazy through the
factory so the no-subscriber path allocates nothing beyond the closure.

Author: logaretm

src/diagnostics.ts

@@ -20,7 +20,7 @@
 export interface MinimalChannel {
   readonly hasSubscribers: boolean;
   publish: (message: unknown) => void;
-  runStores: <T, ContextType>(
+  runStores: <T, ContextType extends object>(
     context: ContextType,
     fn: (this: ContextType, ...args: Array<unknown>) => T,
     thisArg?: unknown,
@@ -125,3 +125,59 @@ export function enableDiagnosticsChannel(dc: MinimalDiagnosticsChannel): void {
     subscribe: dc.tracingChannel('graphql:subscribe'),
   };
 }
+
+/**
+ * Gate for emission sites. Returns `true` when the named channel exists and
+ * publishing should proceed.
+ *
+ * Uses `!== false` rather than a truthy check so runtimes which do not
+ * implement the aggregated `hasSubscribers` getter on `TracingChannel` still
+ * publish. Notably Node 18 (nodejs/node#54470), where the aggregated getter
+ * returns `undefined` while sub-channels behave correctly.
+ *
+ * @internal
+ */
+function shouldTrace(
+  channel: MinimalTracingChannel | undefined,
+): channel is MinimalTracingChannel {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
+  return channel !== undefined && channel.hasSubscribers !== false;
+}
+
+/**
+ * Publish a synchronous operation through the named graphql tracing channel,
+ * short-circuiting to `fn()` when the channel isn't registered or nothing is
+ * listening.
+ *
+ * @internal
+ */
+export function maybeTraceSync<T>(
+  name: keyof GraphQLChannels,
+  ctxFactory: () => object,
+  fn: () => T,
+): T {
+  const channel = getChannels()?.[name];
+  if (!shouldTrace(channel)) {
+    return fn();
+  }
+  return channel.traceSync(fn, ctxFactory());
+}
+
+/**
+ * Publish a promise-returning operation through the named graphql tracing
+ * channel, short-circuiting to `fn()` when the channel isn't registered or
+ * nothing is listening.
+ *
+ * @internal
+ */
+export function maybeTracePromise<T>(
+  name: keyof GraphQLChannels,
+  ctxFactory: () => object,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const channel = getChannels()?.[name];
+  if (!shouldTrace(channel)) {
+    return fn();
+  }
+  return channel.tracePromise(fn, ctxFactory());
+}

src/language/__tests__/parser-diagnostics-test.ts

@@ -0,0 +1,214 @@
+import { expect } from 'chai';
+import { afterEach, beforeEach, describe, it } from 'mocha';
+
+import type {
+  MinimalChannel,
+  MinimalDiagnosticsChannel,
+  MinimalTracingChannel,
+} from '../../diagnostics.js';
+import { enableDiagnosticsChannel } from '../../diagnostics.js';
+
+import { parse } from '../parser.js';
+
+type Listener = (message: unknown) => void;
+
+class FakeChannel implements MinimalChannel {
+  listeners: Array<Listener> = [];
+  get hasSubscribers(): boolean {
+    return this.listeners.length > 0;
+  }
+
+  publish(message: unknown): void {
+    for (const l of this.listeners) {
+      l(message);
+    }
+  }
+
+  runStores<T, ContextType extends object>(
+    _ctx: ContextType,
+    fn: (this: ContextType, ...args: Array<unknown>) => T,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ): T {
+    return fn.apply(thisArg as ContextType, args);
+  }
+
+  subscribe(listener: Listener): void {
+    this.listeners.push(listener);
+  }
+
+  unsubscribe(listener: Listener): void {
+    const idx = this.listeners.indexOf(listener);
+    if (idx >= 0) {
+      this.listeners.splice(idx, 1);
+    }
+  }
+}
+
+class FakeTracingChannel implements MinimalTracingChannel {
+  start = new FakeChannel();
+  end = new FakeChannel();
+  asyncStart = new FakeChannel();
+  asyncEnd = new FakeChannel();
+  error = new FakeChannel();
+
+  get hasSubscribers(): boolean {
+    return (
+      this.start.hasSubscribers ||
+      this.end.hasSubscribers ||
+      this.asyncStart.hasSubscribers ||
+      this.asyncEnd.hasSubscribers ||
+      this.error.hasSubscribers
+    );
+  }
+
+  traceSync<T>(
+    fn: (...args: Array<unknown>) => T,
+    ctx: object,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ): T {
+    this.start.publish(ctx);
+    try {
+      return this.end.runStores(ctx, fn, thisArg, ...args);
+    } catch (err) {
+      (ctx as { error: unknown }).error = err;
+      this.error.publish(ctx);
+      throw err;
+    } finally {
+      this.end.publish(ctx);
+    }
+  }
+
+  tracePromise<T>(
+    fn: (...args: Array<unknown>) => Promise<T>,
+    ctx: object,
+    thisArg?: unknown,
+    ...args: Array<unknown>
+  ): Promise<T> {
+    this.start.publish(ctx);
+    let promise: Promise<T>;
+    try {
+      promise = this.end.runStores(ctx, fn, thisArg, ...args);
+    } catch (err) {
+      (ctx as { error: unknown }).error = err;
+      this.error.publish(ctx);
+      this.end.publish(ctx);
+      throw err;
+    }
+    this.end.publish(ctx);
+    return promise.then(
+      (result) => {
+        (ctx as { result: unknown }).result = result;
+        this.asyncStart.publish(ctx);
+        this.asyncEnd.publish(ctx);
+        return result;
+      },
+      (err: unknown) => {
+        (ctx as { error: unknown }).error = err;
+        this.error.publish(ctx);
+        this.asyncStart.publish(ctx);
+        this.asyncEnd.publish(ctx);
+        throw err;
+      },
+    );
+  }
+}
+
+class FakeDc implements MinimalDiagnosticsChannel {
+  private cache = new Map<string, FakeTracingChannel>();
+
+  tracingChannel(name: string): FakeTracingChannel {
+    let existing = this.cache.get(name);
+    if (existing === undefined) {
+      existing = new FakeTracingChannel();
+      this.cache.set(name, existing);
+    }
+    return existing;
+  }
+}
+
+const fakeDc = new FakeDc();
+const parseChannel = fakeDc.tracingChannel('graphql:parse');
+
+interface Event {
+  kind: 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error';
+  source: unknown;
+  error?: unknown;
+}
+
+function collectEvents(): { events: Array<Event>; unsubscribe: () => void } {
+  const events: Array<Event> = [];
+  const startL: Listener = (m) =>
+    events.push({ kind: 'start', source: (m as { source: unknown }).source });
+  const endL: Listener = (m) =>
+    events.push({ kind: 'end', source: (m as { source: unknown }).source });
+  const asyncStartL: Listener = (m) =>
+    events.push({
+      kind: 'asyncStart',
+      source: (m as { source: unknown }).source,
+    });
+  const asyncEndL: Listener = (m) =>
+    events.push({
+      kind: 'asyncEnd',
+      source: (m as { source: unknown }).source,
+    });
+  const errorL: Listener = (m) => {
+    const msg = m as { source: unknown; error: unknown };
+    events.push({ kind: 'error', source: msg.source, error: msg.error });
+  };
+  parseChannel.start.subscribe(startL);
+  parseChannel.end.subscribe(endL);
+  parseChannel.asyncStart.subscribe(asyncStartL);
+  parseChannel.asyncEnd.subscribe(asyncEndL);
+  parseChannel.error.subscribe(errorL);
+  return {
+    events,
+    unsubscribe() {
+      parseChannel.start.unsubscribe(startL);
+      parseChannel.end.unsubscribe(endL);
+      parseChannel.asyncStart.unsubscribe(asyncStartL);
+      parseChannel.asyncEnd.unsubscribe(asyncEndL);
+      parseChannel.error.unsubscribe(errorL);
+    },
+  };
+}
+
+describe('parse diagnostics channel', () => {
+  let active: ReturnType<typeof collectEvents> | undefined;
+
+  beforeEach(() => {
+    enableDiagnosticsChannel(fakeDc);
+  });
+
+  afterEach(() => {
+    active?.unsubscribe();
+    active = undefined;
+  });
+
+  it('emits start and end around a successful parse', () => {
+    active = collectEvents();
+
+    const doc = parse('{ field }');
+
+    expect(doc.kind).to.equal('Document');
+    expect(active.events.map((e) => e.kind)).to.deep.equal(['start', 'end']);
+    expect(active.events[0].source).to.equal('{ field }');
+    expect(active.events[1].source).to.equal('{ field }');
+  });
+
+  it('emits start, error, and end when the parser throws', () => {
+    active = collectEvents();
+
+    expect(() => parse('{ ')).to.throw();
+
+    const kinds = active.events.map((e) => e.kind);
+    expect(kinds).to.deep.equal(['start', 'error', 'end']);
+    expect(active.events[1].error).to.be.instanceOf(Error);
+  });
+
+  it('does nothing when no subscribers are attached', () => {
+    const doc = parse('{ field }');
+    expect(doc.kind).to.equal('Document');
+  });
+});

src/language/parser.ts

@@ -3,6 +3,8 @@ import type { Maybe } from '../jsutils/Maybe.js';
 import type { GraphQLError } from '../error/GraphQLError.js';
 import { syntaxError } from '../error/syntaxError.js';
 
+import { maybeTraceSync } from '../diagnostics.js';
+
 import type {
   ArgumentCoordinateNode,
   ArgumentNode,
@@ -132,13 +134,19 @@ export function parse(
   source: string | Source,
   options?: ParseOptions,
 ): DocumentNode {
-  const parser = new Parser(source, options);
-  const document = parser.parseDocument();
-  Object.defineProperty(document, 'tokenCount', {
-    enumerable: false,
-    value: parser.tokenCount,
-  });
-  return document;
+  return maybeTraceSync(
+    'parse',
+    () => ({ source }),
+    () => {
+      const parser = new Parser(source, options);
+      const document = parser.parseDocument();
+      Object.defineProperty(document, 'tokenCount', {
+        enumerable: false,
+        value: parser.tokenCount,
+      });
+      return document;
+    },
+  );
 }
 
 /**