feat: add mongoose:cursor:next TracingChannel for cursor iteration

Adds a dedicated `mongoose:cursor:next` channel that traces each
`next()` call on both QueryCursor and AggregationCursor. Kept separate
from `mongoose:query` so APMs can subscribe independently and a future
`mongoose:cursor` parent span channel won't conflict.

Also refactors tracing.js: bulletproof dc import with process guard and
try/catch, and a createTracedChannel factory to eliminate duplication.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: logaretm

lib/cursor/aggregationCursor.js

@@ -10,6 +10,7 @@ const eachAsync = require('../helpers/cursor/eachAsync');
 const immediate = require('../helpers/immediate');
 const kareem = require('kareem');
 const util = require('util');
+const { traceCursorNext } = require('../tracing');
 
 /**
  * An AggregationCursor is a concurrency primitive for processing aggregation
@@ -277,14 +278,28 @@ AggregationCursor.prototype.next = async function next() {
   if (typeof arguments[0] === 'function') {
     throw new MongooseError('AggregationCursor.prototype.next() no longer accepts a callback');
   }
-  return new Promise((resolve, reject) => {
-    _next(this, (err, res) => {
-      if (err != null) {
-        return reject(err);
-      }
-      resolve(res);
+  const _this = this;
+  const model = this.agg._model;
+  return traceCursorNext(function maybeTracedAggCursorNext() {
+    return new Promise((resolve, reject) => {
+      _next(_this, (err, res) => {
+        if (err != null) {
+          return reject(err);
+        }
+        resolve(res);
+      });
     });
-  });
+  }, () => ({
+    operation: 'aggregate',
+    collection: model?.collection?.name,
+    database: model?.db?.name,
+    serverAddress: model?.db?.host,
+    serverPort: model?.db?.port,
+    args: {
+      pipeline: _this.agg._pipeline,
+      options: _this.agg.options
+    }
+  }));
 };
 
 /**

lib/cursor/queryCursor.js

@@ -12,6 +12,7 @@ const kareem = require('kareem');
 const immediate = require('../helpers/immediate');
 const { once } = require('events');
 const util = require('util');
+const { traceCursorNext } = require('../tracing');
 
 /**
  * A QueryCursor is a concurrency primitive for processing query results
@@ -310,14 +311,27 @@ QueryCursor.prototype.next = async function next() {
   if (this._closed) {
     throw new MongooseError('Cannot call `next()` on a closed cursor');
   }
-  return new Promise((resolve, reject) => {
-    _next(this, function(error, doc) {
-      if (error) {
-        return reject(error);
-      }
-      resolve(doc);
+  const _this = this;
+  return traceCursorNext(function maybeTracedQueryCursorNext() {
+    return new Promise((resolve, reject) => {
+      _next(_this, function(error, doc) {
+        if (error) {
+          return reject(error);
+        }
+        resolve(doc);
+      });
     });
-  });
+  }, () => ({
+    operation: _this.query.op || 'find',
+    collection: _this.query.mongooseCollection.name,
+    database: _this.model.db?.name,
+    serverAddress: _this.model.db?.host,
+    serverPort: _this.model.db?.port,
+    args: {
+      filter: _this.query.getFilter(),
+      options: _this.query._mongooseOptions
+    }
+  }));
 };
 
 /**

lib/tracing.js

@@ -1,8 +1,15 @@
 'use strict';
 
-const dc = process.getBuiltinModule('node:diagnostics_channel');
+let dc;
+try {
+  dc = (typeof process !== 'undefined' && 'getBuiltinModule' in process)
+    ? process.getBuiltinModule('node:diagnostics_channel')
+    : require('node:diagnostics_channel');
+} catch {
+  // diagnostics_channel not available
+}
 
-const hasTracingChannel = typeof dc.tracingChannel === 'function';
+const hasTracingChannel = !!dc && typeof dc.tracingChannel === 'function';
 
 function shouldTrace(channel) {
   // Node 18 and Bun don't expose hasSubscribers on TracingChannel
@@ -12,21 +19,29 @@ function shouldTrace(channel) {
 
 const noop = () => {};
 
-const channel = hasTracingChannel
-  ? dc.tracingChannel('mongoose:query')
-  : undefined;
+function createTracedChannel(name) {
+  const ch = hasTracingChannel ? dc.tracingChannel(name) : undefined;
+
+  function trace(fn, contextFactory) {
+    if (!shouldTrace(ch)) {
+      return fn();
+    }
 
-function trace(fn, contextFactory) {
-  if (shouldTrace(channel)) {
-    const traced = channel.tracePromise(fn, contextFactory());
+    const traced = ch.tracePromise(fn, contextFactory());
     traced.catch(noop);
     return traced;
   }
-  return fn();
+
+  return { channel: ch, trace };
 }
 
+const query = createTracedChannel('mongoose:query');
+const cursorNext = createTracedChannel('mongoose:cursor:next');
+
 module.exports = {
-  channel,
-  trace,
+  channel: query.channel,
+  cursorNextChannel: cursorNext.channel,
+  trace: query.trace,
+  traceCursorNext: cursorNext.trace,
   shouldTrace
 };

test/tracing.test.js

@@ -3,7 +3,7 @@
 const assert = require('assert');
 const mongoose = require('../index');
 
-const { channel } = require('../lib/tracing');
+const { channel, cursorNextChannel } = require('../lib/tracing');
 
 describe('TracingChannel', function() {
   let conn;
@@ -383,6 +383,131 @@ describe('TracingChannel', function() {
     });
   });
 
+  describe('cursor:next operations', function() {
+    it('fires start and asyncEnd for query cursor next()', async function() {
+      await Test.create([
+        { name: 'cursor1', age: 10 },
+        { name: 'cursor2', age: 20 }
+      ]);
+
+      const events = [];
+      const handlers = {
+        start(ctx) { events.push({ event: 'start', ...ctx }); },
+        end() { events.push({ event: 'end' }); },
+        asyncStart(ctx) { events.push({ event: 'asyncStart', result: ctx.result }); },
+        asyncEnd(ctx) { events.push({ event: 'asyncEnd', result: ctx.result }); },
+        error(ctx) { events.push({ event: 'error', error: ctx.error }); }
+      };
+
+      cursorNextChannel.subscribe(handlers);
+      try {
+        const cursor = Test.find({ name: /^cursor/ }).sort({ name: 1 }).cursor();
+        const doc1 = await cursor.next();
+        const doc2 = await cursor.next();
+        const doc3 = await cursor.next();
+
+        assert.strictEqual(doc1.name, 'cursor1');
+        assert.strictEqual(doc2.name, 'cursor2');
+        assert.strictEqual(doc3, null);
+
+        const starts = events.filter(e => e.event === 'start');
+        assert.strictEqual(starts.length, 3, 'should fire start for each next() call');
+        assert.strictEqual(starts[0].operation, 'find');
+        assert.strictEqual(starts[0].collection, collectionName);
+        assert.ok(starts[0].database);
+
+        const asyncEnds = events.filter(e => e.event === 'asyncEnd');
+        assert.strictEqual(asyncEnds.length, 3, 'should fire asyncEnd for each next() call');
+      } finally {
+        cursorNextChannel.unsubscribe(handlers);
+      }
+    });
+
+    it('fires start and asyncEnd for aggregate cursor next()', async function() {
+      await Test.create([
+        { name: 'agg-cursor1', age: 10 },
+        { name: 'agg-cursor2', age: 20 }
+      ]);
+
+      const events = [];
+      const handlers = {
+        start(ctx) { events.push({ event: 'start', ...ctx }); },
+        end() { events.push({ event: 'end' }); },
+        asyncStart() {},
+        asyncEnd(ctx) { events.push({ event: 'asyncEnd', result: ctx.result }); },
+        error() {}
+      };
+
+      cursorNextChannel.subscribe(handlers);
+      try {
+        const cursor = Test.aggregate([
+          { $match: { name: /^agg-cursor/ } },
+          { $sort: { name: 1 } }
+        ]).cursor();
+
+        const doc1 = await cursor.next();
+        const doc2 = await cursor.next();
+        const doc3 = await cursor.next();
+
+        assert.strictEqual(doc1.name, 'agg-cursor1');
+        assert.strictEqual(doc2.name, 'agg-cursor2');
+        assert.strictEqual(doc3, null);
+
+        const starts = events.filter(e => e.event === 'start');
+        assert.strictEqual(starts.length, 3, 'should fire start for each next() call');
+        assert.strictEqual(starts[0].operation, 'aggregate');
+        assert.strictEqual(starts[0].collection, collectionName);
+        assert.ok(starts[0].database);
+        assert.ok(Array.isArray(starts[0].args.pipeline));
+      } finally {
+        cursorNextChannel.unsubscribe(handlers);
+      }
+    });
+
+    it('fires error event on cursor next() failure', async function() {
+      const events = [];
+      const handlers = {
+        start() { events.push({ event: 'start' }); },
+        end() {},
+        asyncStart() {},
+        asyncEnd() {},
+        error(ctx) { events.push({ event: 'error', error: ctx.error }); }
+      };
+
+      cursorNextChannel.subscribe(handlers);
+      try {
+        const cursor = Test.find({ $invalidOperator: true }).cursor();
+        await cursor.next().catch(() => {});
+
+        assert.ok(events.some(e => e.event === 'start'), 'start should fire');
+        assert.ok(events.some(e => e.event === 'error'), 'error should fire');
+      } finally {
+        cursorNextChannel.unsubscribe(handlers);
+      }
+    });
+
+    it('does not fire cursor:next events when using regular find()', async function() {
+      await Test.create({ name: 'no-cursor', age: 5 });
+
+      const events = [];
+      const handlers = {
+        start() { events.push({ event: 'start' }); },
+        end() {},
+        asyncStart() {},
+        asyncEnd() {},
+        error() {}
+      };
+
+      cursorNextChannel.subscribe(handlers);
+      try {
+        await Test.find({ name: 'no-cursor' });
+        assert.strictEqual(events.length, 0, 'cursor:next should not fire for regular find()');
+      } finally {
+        cursorNextChannel.unsubscribe(handlers);
+      }
+    });
+  });
+
   describe('zero-cost when no subscribers', function() {
     it('operations work without any subscribers', async function() {
       const doc = new Test({ name: 'no-sub', age: 5 });
@@ -401,5 +526,16 @@ describe('TracingChannel', function() {
 
       await Test.deleteMany({ name: /^no-sub/ });
     });
+
+    it('cursor next() works without any subscribers', async function() {
+      await Test.create({ name: 'no-sub-cursor', age: 5 });
+
+      const cursor = Test.find({ name: 'no-sub-cursor' }).cursor();
+      const doc = await cursor.next();
+      assert.strictEqual(doc.name, 'no-sub-cursor');
+
+      const done = await cursor.next();
+      assert.strictEqual(done, null);
+    });
   });
 });