feat(execution): publish on graphql:execute tracing channel

Wraps the public execute / experimentalExecuteIncrementally /
executeIgnoringIncremental / executeSubscriptionEvent entry points with
maybeTraceMixed so subscribers see a single graphql:execute span per
top-level operation invocation, including every per-event execution of
a subscription stream.

The context exposes the document, schema, variableValues, operationName,
and operationType. operationName and operationType are lazy getters that
only resolve the operation AST (getOperationAST) if a subscriber reads
them, keeping the gate cheap for APMs that do not need them. The
ValidatedExecutionArgs variant used by executeSubscriptionEvent uses the
already-resolved operation from validation and therefore needs no lazy
lookup; it carries the resolved operation in place of the (unavailable)
document.

Adds a shared maybeTraceMixed helper to src/diagnostics.ts for
PromiseOrValue-returning functions. It delegates start / end / error to
Node's traceSync (which also runs fn inside end.runStores for
AsyncLocalStorage propagation) and adds the asyncStart / asyncEnd /
error-on-rejection emission when the return value is a promise.

Author: logaretm

integrationTests/diagnostics/test.js

@@ -8,6 +8,7 @@ import dc from 'node:diagnostics_channel';
 import {
   buildSchema,
   enableDiagnosticsChannel,
+  execute,
   parse,
   validate,
 } from 'graphql';
@@ -103,6 +104,51 @@ enableDiagnosticsChannel(dc);
   }
 }
 
+// graphql:execute - sync path, ctx carries operationType, operationName,
+// document, schema.
+{
+  const schema = buildSchema(`type Query { hello: String }`);
+  const document = parse('query Greeting { hello }');
+
+  const events = [];
+  const handler = {
+    start: (msg) =>
+      events.push({
+        kind: 'start',
+        operationType: msg.operationType,
+        operationName: msg.operationName,
+        document: msg.document,
+        schema: msg.schema,
+      }),
+    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);
+  }
+}
+
 // No-op when nothing is subscribed - parse still succeeds.
 {
   const doc = parse('{ field }');

src/diagnostics.ts

@@ -13,6 +13,8 @@
  * same `TracingChannel` instances and all subscribers coexist.
  */
 
+import { isPromise } from './jsutils/isPromise.js';
+
 /**
  * Structural subset of `DiagnosticsChannel` sufficient for publishing and
  * subscriber gating. `node:diagnostics_channel`'s `Channel` satisfies this.
@@ -181,3 +183,52 @@ export function maybeTracePromise<T>(
   }
   return channel.tracePromise(fn, ctxFactory());
 }
+
+/**
+ * Publish a mixed sync-or-promise operation through the named graphql tracing
+ * channel. Delegates the start/end/error lifecycle to Node's `traceSync`
+ * (which also runs `fn` inside `end.runStores` for AsyncLocalStorage context
+ * propagation) and, when `fn` returns a promise, appends `asyncStart` and
+ * `asyncEnd` on settlement plus `error` on rejection.
+ *
+ * Use this when the function may return either a value or a promise, which
+ * is common on graphql-js's execution path where async-ness is determined
+ * by resolvers only after the call begins. Short-circuits to `fn()` when
+ * the channel isn't registered or nothing is listening.
+ *
+ * @internal
+ */
+export function maybeTraceMixed<T>(
+  name: keyof GraphQLChannels,
+  ctxFactory: () => object,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  const channel = getChannels()?.[name];
+  if (!shouldTrace(channel)) {
+    return fn();
+  }
+  const ctx = ctxFactory() as {
+    error?: unknown;
+    result?: unknown;
+  };
+  const result = channel.traceSync(fn, ctx);
+  if (!isPromise(result)) {
+    ctx.result = result;
+    return result;
+  }
+  return result.then(
+    (value) => {
+      ctx.result = value;
+      channel.asyncStart.publish(ctx);
+      channel.asyncEnd.publish(ctx);
+      return value;
+    },
+    (err: unknown) => {
+      ctx.error = err;
+      channel.error.publish(ctx);
+      channel.asyncStart.publish(ctx);
+      channel.asyncEnd.publish(ctx);
+      throw err;
+    },
+  );
+}

src/execution/__tests__/execute-diagnostics-test.ts

@@ -0,0 +1,139 @@
+import { expect } from 'chai';
+import { afterEach, beforeEach, describe, it } from 'mocha';
+
+import {
+  collectEvents,
+  FakeDc,
+} from '../../__testUtils__/fakeDiagnosticsChannel.js';
+
+import { parse } from '../../language/parser.js';
+
+import { buildSchema } from '../../utilities/buildASTSchema.js';
+
+import { enableDiagnosticsChannel } from '../../diagnostics.js';
+
+import type { ExecutionArgs } from '../execute.js';
+import {
+  execute,
+  executeSubscriptionEvent,
+  executeSync,
+  validateExecutionArgs,
+} from '../execute.js';
+
+const schema = buildSchema(`
+  type Query {
+    sync: String
+    async: String
+  }
+`);
+
+const rootValue = {
+  sync: () => 'hello',
+  async: () => Promise.resolve('hello-async'),
+};
+
+const fakeDc = new FakeDc();
+const executeChannel = fakeDc.tracingChannel('graphql:execute');
+
+describe('execute diagnostics channel', () => {
+  let active: ReturnType<typeof collectEvents> | undefined;
+
+  beforeEach(() => {
+    enableDiagnosticsChannel(fakeDc);
+  });
+
+  afterEach(() => {
+    active?.unsubscribe();
+    active = undefined;
+  });
+
+  it('emits start and end around a synchronous execute', () => {
+    active = collectEvents(executeChannel);
+
+    const document = parse('query Q { sync }');
+    const result = execute({ schema, document, rootValue });
+
+    expect(result).to.deep.equal({ data: { sync: 'hello' } });
+    expect(active.events.map((e) => e.kind)).to.deep.equal(['start', 'end']);
+    expect(active.events[0].ctx.operationType).to.equal('query');
+    expect(active.events[0].ctx.operationName).to.equal('Q');
+    expect(active.events[0].ctx.document).to.equal(document);
+    expect(active.events[0].ctx.schema).to.equal(schema);
+  });
+
+  it('emits start, end, and async lifecycle when execute returns a promise', async () => {
+    active = collectEvents(executeChannel);
+
+    const document = parse('query { async }');
+    const result = await execute({ schema, document, rootValue });
+
+    expect(result).to.deep.equal({ data: { async: 'hello-async' } });
+    expect(active.events.map((e) => e.kind)).to.deep.equal([
+      'start',
+      'end',
+      'asyncStart',
+      'asyncEnd',
+    ]);
+  });
+
+  it('emits once for executeSync via experimentalExecuteIncrementally', () => {
+    active = collectEvents(executeChannel);
+
+    const document = parse('{ sync }');
+    executeSync({ schema, document, rootValue });
+
+    expect(active.events.map((e) => e.kind)).to.deep.equal(['start', 'end']);
+  });
+
+  it('emits start, error, and end when execute throws synchronously', () => {
+    active = collectEvents(executeChannel);
+
+    const schemaWithDefer = buildSchema(`
+      directive @defer on FIELD
+      type Query { sync: String }
+    `);
+    const document = parse('{ sync }');
+    expect(() =>
+      execute({ schema: schemaWithDefer, document, rootValue }),
+    ).to.throw();
+
+    expect(active.events.map((e) => e.kind)).to.deep.equal([
+      'start',
+      'error',
+      'end',
+    ]);
+  });
+
+  it('emits for each executeSubscriptionEvent call with resolved operation ctx', () => {
+    const args: ExecutionArgs = {
+      schema,
+      document: parse('query Q { sync }'),
+      rootValue,
+    };
+    const validated = validateExecutionArgs(args);
+    if (!('schema' in validated)) {
+      throw new Error('unexpected validation failure');
+    }
+
+    active = collectEvents(executeChannel);
+
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    executeSubscriptionEvent(validated);
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    executeSubscriptionEvent(validated);
+
+    const starts = active.events.filter((e) => e.kind === 'start');
+    expect(starts.length).to.equal(2);
+    for (const ev of starts) {
+      expect(ev.ctx.operationType).to.equal('query');
+      expect(ev.ctx.operationName).to.equal('Q');
+      expect(ev.ctx.schema).to.equal(schema);
+    }
+  });
+
+  it('does nothing when no subscribers are attached', () => {
+    const document = parse('{ sync }');
+    const result = execute({ schema, document, rootValue });
+    expect(result).to.deep.equal({ data: { sync: 'hello' } });
+  });
+});