feat(mongoose): Instrument mongoose >= 9.7 via native tracing channels

dev-packages/node-integration-tests/suites/tracing/mongoose-tracing-channel/instrument.mjs

@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});

dev-packages/node-integration-tests/suites/tracing/mongoose-tracing-channel/scenario.mjs

@@ -0,0 +1,48 @@
+import * as Sentry from '@sentry/node';
+import mongoose from 'mongoose';
+
+async function run() {
+  await mongoose.connect(process.env.MONGO_URL || '');
+
+  const BlogPostSchema = new mongoose.Schema({
+    title: String,
+    body: String,
+    date: Date,
+  });
+
+  const BlogPost = mongoose.model('BlogPost', BlogPostSchema);
+
+  await Sentry.startSpan(
+    {
+      name: 'Test Transaction',
+      op: 'transaction',
+    },
+    async () => {
+      const post = new BlogPost({ title: 'Test', body: 'Test body', date: new Date() });
+      await post.save();
+
+      // Filter with a real value, to assert it is redacted out of `db.query.text`.
+      await BlogPost.findOne({ title: 'Test' });
+
+      await BlogPost.aggregate([{ $match: { title: 'Test' } }]);
+
+      await BlogPost.insertMany([
+        { title: 'Insert1', body: 'b', date: new Date() },
+        { title: 'Insert2', body: 'b', date: new Date() },
+      ]);
+
+      await BlogPost.bulkWrite([
+        { insertOne: { document: { title: 'Bulk1', body: 'b', date: new Date() } } },
+        { insertOne: { document: { title: 'Bulk2', body: 'b', date: new Date() } } },
+      ]);
+
+      // Drive a cursor to exercise the `mongoose:cursor:next` channel.
+      const cursor = BlogPost.find().cursor();
+      for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
+        // iterate
+      }
+    },
+  );
+}
+
+run();

dev-packages/node-integration-tests/suites/tracing/mongoose-tracing-channel/test.ts

@@ -0,0 +1,118 @@
+import { MongoMemoryServer } from 'mongodb-memory-server-global';
+import { afterAll, beforeAll, expect } from 'vitest';
+import { conditionalTest } from '../../../utils';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+// mongoose >= 9.7.0 publishes its operations via `node:diagnostics_channel`, so the SDK subscribes
+// to those channels (`subscribeMongooseDiagnosticChannels`) instead of monkey-patching. This suite
+// pins `^9.7` and asserts the diagnostics-channel path: stable OTel DB semconv attributes, redacted
+// query text, span relationships, and that the legacy IITM patcher does NOT also fire (no double
+// instrumentation). mongoose 9 requires Node >=20.19, so this suite is skipped on older Node.
+conditionalTest({ min: 20 })('Mongoose tracing channel Test', () => {
+  let mongoServer: MongoMemoryServer;
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create();
+    process.env.MONGO_URL = mongoServer.getUri();
+  }, 30000);
+
+  afterAll(async () => {
+    if (mongoServer) {
+      await mongoServer.stop();
+    }
+    cleanupChildProcesses();
+  });
+
+  const expectedSpan = (operation: string, extraData: Record<string, unknown> = {}) =>
+    expect.objectContaining({
+      data: expect.objectContaining({
+        'db.system.name': 'mongodb',
+        'db.namespace': 'test',
+        'db.collection.name': 'blogposts',
+        'db.operation.name': operation,
+        'server.address': expect.any(String),
+        'server.port': expect.any(Number),
+        ...extraData,
+      }),
+      description: `mongoose.blogposts.${operation}`,
+      op: 'db',
+      origin: 'auto.db.mongoose.diagnostic_channel',
+    });
+
+  const EXPECTED_TRANSACTION = {
+    transaction: 'Test Transaction',
+    spans: expect.arrayContaining([
+      expectedSpan('save'),
+      // filter values are redacted out of `db.query.text`
+      expectedSpan('findOne', { 'db.query.text': '{"title":"?"}' }),
+      expectedSpan('aggregate', { 'db.query.text': '[{"$match":{"title":"?"}}]' }),
+      expectedSpan('insertMany', { 'db.operation.batch.size': 2 }),
+      expectedSpan('bulkWrite', { 'db.operation.batch.size': 2 }),
+      // a cursor iteration emits a span per `.next()` via the `mongoose:cursor:next` channel
+      expectedSpan('find'),
+    ]),
+  };
+
+  createEsmAndCjsTests(
+    __dirname,
+    'scenario.mjs',
+    'instrument.mjs',
+    (createTestRunner, test) => {
+      test('subscribes to mongoose >= 9.7 diagnostics channels with stable semconv attributes', async () => {
+        await createTestRunner().expect({ transaction: EXPECTED_TRANSACTION }).start().completed();
+      });
+
+      test('does not double-instrument: the legacy IITM mongoose patcher does not fire on 9.7', async () => {
+        await createTestRunner()
+          .expect({
+            transaction: event => {
+              const spans = event.spans || [];
+              // The monkey-patch path (origin `auto.db.otel.mongoose`) must be inactive on 9.7+.
+              expect(spans.find(span => span.origin === 'auto.db.otel.mongoose')).toBeUndefined();
+              // ...while the diagnostics-channel path is active.
+              expect(spans.find(span => span.origin === 'auto.db.mongoose.diagnostic_channel')).toBeDefined();
+            },
+          })
+          .start()
+          .completed();
+      });
+
+      test('never leaks raw filter values into db.query.text', async () => {
+        await createTestRunner()
+          .expect({
+            transaction: event => {
+              const spans = event.spans || [];
+              for (const span of spans) {
+                const queryText = span.data?.['db.query.text'];
+                if (typeof queryText === 'string') {
+                  expect(queryText).not.toContain('Test');
+                }
+              }
+            },
+          })
+          .start()
+          .completed();
+      });
+
+      test('nests the mongodb driver span under the mongoose channel span', async () => {
+        await createTestRunner()
+          .expect({
+            transaction: event => {
+              const spans = event.spans || [];
+              const mongooseSave = spans.find(span => span.description === 'mongoose.blogposts.save');
+              expect(mongooseSave).toBeDefined();
+              // the underlying mongodb driver span must parent to the mongoose channel span,
+              // proving the channel span is the active async context for the traced operation
+              const driverChild = spans.find(
+                span => span.parent_span_id === mongooseSave?.span_id && span.origin === 'auto.db.otel.mongo',
+              );
+              expect(driverChild).toBeDefined();
+            },
+          })
+          .start()
+          .completed();
+      });
+    },
+    { additionalDependencies: { mongoose: '^9.7' } },
+  );
+});

dev-packages/node-integration-tests/suites/tracing/mongoose-v9/test.ts

@@ -3,8 +3,10 @@ import { afterAll, beforeAll, expect } from 'vitest';
 import { conditionalTest } from '../../../utils';
 import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
 
-// Pins mongoose 9 (top of our supported `>=5.9.7 <10` range) so the latest major is exercised
-// against a real mongoose. mongoose 9 requires Node >=20.19, so this suite is skipped on older Node.
+// Pins the highest mongoose 9 below 9.7, the top of the IITM patcher's `>=5.9.7 <9.7.0` range, so the
+// monkey-patch path is exercised against a real mongoose 9. mongoose >= 9.7 publishes via
+// diagnostics_channel and is covered by the `mongoose-tracing-channel` suite instead.
+// mongoose 9 requires Node >=20.19, so this suite is skipped on older Node.
 conditionalTest({ min: 20 })('Mongoose v9 Test', () => {
   let mongoServer: MongoMemoryServer;
 
@@ -55,6 +57,6 @@ conditionalTest({ min: 20 })('Mongoose v9 Test', () => {
         await createTestRunner().expect({ transaction: EXPECTED_TRANSACTION }).start().completed();
       });
     },
-    { additionalDependencies: { mongoose: '^9' } },
+    { additionalDependencies: { mongoose: '>=9 <9.7' } },
   );
 });

packages/node/src/integrations/tracing/mongoose/index.ts

@@ -1,19 +1,22 @@
 import { MongooseInstrumentation } from './vendored/mongoose';
 import type { IntegrationFn } from '@sentry/core';
-import { defineIntegration } from '@sentry/core';
+import { defineIntegration, extendIntegration } from '@sentry/core';
 import { generateInstrumentOnce } from '@sentry/node-core';
+import { mongooseIntegration as mongooseChannelIntegration } from '@sentry/server-utils';
 
 const INTEGRATION_NAME = 'Mongoose' as const;
 
 export const instrumentMongoose = generateInstrumentOnce(INTEGRATION_NAME, () => new MongooseInstrumentation());
 
 const _mongooseIntegration = (() => {
-  return {
+  // The diagnostics_channel subscription (mongoose >= 9.7) lives in server-utils so it is shared
+  // across server runtimes; we extend it here to also run the IITM-based patcher for mongoose < 9.7.
+  return extendIntegration(mongooseChannelIntegration(), {
     name: INTEGRATION_NAME,
     setupOnce() {
       instrumentMongoose();
     },
-  };
+  });
 }) satisfies IntegrationFn;
 
 /**

packages/node/src/integrations/tracing/mongoose/vendored/mongoose.ts

@@ -107,7 +107,10 @@ export class MongooseInstrumentation extends InstrumentationBase<Instrumentation
   protected init(): InstrumentationModuleDefinition {
     const module = new InstrumentationNodeModuleDefinition(
       'mongoose',
-      ['>=5.9.7 <10'],
+      // mongoose >= 9.7.0 publishes via diagnostics_channel and is instrumented by
+      // `subscribeMongooseDiagnosticChannels` instead, so this IITM patcher must not
+      // overlap it — otherwise every operation would emit two mongoose spans.
+      ['>=5.9.7 <9.7.0'],
       this.patch.bind(this),
       this.unpatch.bind(this),
     );

packages/server-utils/src/index.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+export { mongooseIntegration } from './mongoose';
 export {
   IOREDIS_DC_CHANNEL_COMMAND,
   IOREDIS_DC_CHANNEL_CONNECT,

packages/server-utils/src/mongoose/index.ts

@@ -0,0 +1,30 @@
+import { defineIntegration, type IntegrationFn, waitForTracingChannelBinding } from '@sentry/core';
+import * as dc from 'node:diagnostics_channel';
+import { subscribeMongooseDiagnosticChannels } from './mongoose-dc-subscriber';
+
+const _mongooseIntegration = (() => {
+  return {
+    name: 'Mongoose',
+    setupOnce() {
+      // Bail on Node <= 18.18.0, where `tracingChannel` does not exist.
+      if (!dc.tracingChannel) {
+        return;
+      }
+
+      // Subscribe to mongoose's native tracing channels (mongoose >= 9.7).
+      // This is a no-op on versions that don't publish to the channels, so it is always safe to call.
+      waitForTracingChannelBinding(() => {
+        subscribeMongooseDiagnosticChannels(dc.tracingChannel);
+      });
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Auto-instrument the [mongoose](https://www.npmjs.com/package/mongoose) library via its native
+ * `node:diagnostics_channel` tracing channels (mongoose >= 9.7).
+ *
+ * On older mongoose versions the channels are never published to, so this integration is inert and
+ * the IITM-based patcher (gated to `< 9.7.0`) handles instrumentation instead.
+ */
+export const mongooseIntegration = defineIntegration(_mongooseIntegration);