@sentienguard/apm 1.0.8 → 1.0.10

package/src/mongodb.js

@@ -1,397 +1,579 @@
-/**
- * MongoDB Instrumentation Module
- *
- * Hooks into MongoDB driver's command monitoring events to track:
- * - Query operations (find, insert, update, delete, aggregate)
- * - Latency and error rates per collection
- * - Connection pool statistics
- * - Slow query detection
- *
- * Uses MongoDB driver's built-in APM events (no monkey-patching):
- * - commandStarted: Record start time
- * - commandSucceeded: Calculate latency, record success
- * - commandFailed: Record failure with error info
- */
-
-import config, { debug, warn } from './config.js';
-import { getAggregator } from './aggregator.js';
-
-// Track pending commands by requestId
-const pendingCommands = new Map();
-
-// Track connection pool stats via CMAP events
-const poolStats = {
-  totalCreated: 0,
-  totalClosed: 0,
-  checkedOut: 0,
-  checkedIn: 0,
-  waitQueueSize: 0
-};
-
-// Operations we want to track (skip admin/internal commands)
-const TRACKED_OPERATIONS = new Set([
-  'find', 'findOne', 'findAndModify',
-  'insert', 'insertOne', 'insertMany',
-  'update', 'updateOne', 'updateMany',
-  'delete', 'deleteOne', 'deleteMany',
-  'aggregate', 'count', 'countDocuments', 'estimatedDocumentCount',
-  'distinct', 'mapReduce',
-  'createIndexes', 'dropIndexes',
-  'bulkWrite'
-]);
-
-// Commands to ignore (internal/admin)
-const IGNORED_COMMANDS = new Set([
-  'hello', 'ismaster', 'isMaster', 'buildInfo', 'getLastError',
-  'ping', 'serverStatus', 'replSetGetStatus', 'hostInfo',
-  'listCollections', 'listIndexes', 'collStats', 'dbStats',
-  'saslStart', 'saslContinue', 'getnonce', 'authenticate'
-]);
-
-let mongoClient = null;
-let poolStatsInterval = null;
-
-/**
- * Extract collection name from command
- */
-function getCollectionName(command) {
-  // Most commands have collection name as the value of the command key
-  const commandName = Object.keys(command)[0];
-  const value = command[commandName];
-
-  // For aggregate, the collection is the value
-  if (typeof value === 'string' && value.length > 0 && value !== '1') {
-    return value;
-  }
-
-  // Check common collection name fields
-  if (command.collection) return command.collection;
-  if (command.ns) {
-    const parts = command.ns.split('.');
-    return parts.length > 1 ? parts.slice(1).join('.') : parts[0];
-  }
-
-  return 'unknown';
-}
-
-/**
- * Normalize operation name
- */
-function normalizeOperation(commandName) {
-  const name = commandName.toLowerCase();
-
-  // Group similar operations
-  if (name.includes('find')) return 'find';
-  if (name.includes('insert')) return 'insert';
-  if (name.includes('update')) return 'update';
-  if (name.includes('delete') || name.includes('remove')) return 'delete';
-  if (name === 'aggregate') return 'aggregate';
-  if (name.includes('count')) return 'count';
-  if (name.includes('index')) return 'index';
-
-  return name;
-}
-
-/**
- * Handle command started event
- */
-function handleCommandStarted(event) {
-  if (!config.mongodb.enabled) return;
-
-  const commandName = event.commandName;
-
-  // Skip ignored commands
-  if (IGNORED_COMMANDS.has(commandName)) {
-    return;
-  }
-
-  // Store start time for latency calculation
-  pendingCommands.set(event.requestId, {
-    startTime: process.hrtime.bigint(),
-    commandName,
-    collection: getCollectionName(event.command),
-    databaseName: event.databaseName
-  });
-
-  debug(`MongoDB command started: ${commandName} on ${event.databaseName}`);
-}
-
-/**
- * Handle command succeeded event
- */
-function handleCommandSucceeded(event) {
-  if (!config.mongodb.enabled) return;
-
-  const pending = pendingCommands.get(event.requestId);
-  if (!pending) return;
-
-  pendingCommands.delete(event.requestId);
-
-  // Calculate latency in milliseconds
-  const latencyNs = process.hrtime.bigint() - pending.startTime;
-  const latencyMs = Number(latencyNs) / 1e6;
-
-  // Record the operation
-  const aggregator = getAggregator();
-  const operation = normalizeOperation(pending.commandName);
-
-  aggregator.recordMongoOperation(
-    pending.collection,
-    operation,
-    latencyMs,
-    false // not an error
-  );
-
-  // Check for slow query
-  if (latencyMs > config.mongodb.slowQueryMs) {
-    aggregator.recordSlowQuery(
-      pending.collection,
-      operation,
-      latencyMs
-    );
-    debug(`Slow MongoDB query: ${operation} on ${pending.collection} took ${latencyMs.toFixed(2)}ms`);
-  }
-
-  debug(`MongoDB command succeeded: ${pending.commandName} (${latencyMs.toFixed(2)}ms)`);
-}
-
-/**
- * Handle command failed event
- */
-function handleCommandFailed(event) {
-  if (!config.mongodb.enabled) return;
-
-  const pending = pendingCommands.get(event.requestId);
-  if (!pending) return;
-
-  pendingCommands.delete(event.requestId);
-
-  // Calculate latency in milliseconds
-  const latencyNs = process.hrtime.bigint() - pending.startTime;
-  const latencyMs = Number(latencyNs) / 1e6;
-
-  // Record the failed operation
-  const aggregator = getAggregator();
-  const operation = normalizeOperation(pending.commandName);
-
-  aggregator.recordMongoOperation(
-    pending.collection,
-    operation,
-    latencyMs,
-    true // is an error
-  );
-
-  warn(`MongoDB command failed: ${pending.commandName} - ${event.failure?.message || 'Unknown error'}`);
-}
-
-/**
- * CMAP Event Handlers for Connection Pool Monitoring
- */
-function handleConnectionCreated(event) {
-  poolStats.totalCreated++;
-  debug(`MongoDB connection created (total: ${poolStats.totalCreated})`);
-}
-
-function handleConnectionClosed(event) {
-  poolStats.totalClosed++;
-  debug(`MongoDB connection closed (total closed: ${poolStats.totalClosed})`);
-}
-
-function handleConnectionCheckedOut(event) {
-  poolStats.checkedOut++;
-  debug(`MongoDB connection checked out (active: ${poolStats.checkedOut - poolStats.checkedIn})`);
-}
-
-function handleConnectionCheckedIn(event) {
-  poolStats.checkedIn++;
-  debug(`MongoDB connection checked in (active: ${poolStats.checkedOut - poolStats.checkedIn})`);
-}
-
-function handleConnectionCheckOutStarted(event) {
-  poolStats.waitQueueSize++;
-}
-
-function handleConnectionCheckOutFailed(event) {
-  poolStats.waitQueueSize = Math.max(0, poolStats.waitQueueSize - 1);
-}
-
-function handleConnectionPoolCreated(event) {
-  debug(`MongoDB connection pool created: ${event.address}`);
-}
-
-/**
- * Collect connection pool statistics
- * Now uses tracked CMAP events for accurate stats
- */
-function collectPoolStats() {
-  if (!mongoClient || !config.mongodb.enabled) return;
-
-  try {
-    const aggregator = getAggregator();
-
-    // Calculate current pool state from tracked events
-    const totalConnections = poolStats.totalCreated - poolStats.totalClosed;
-    const activeConnections = poolStats.checkedOut - poolStats.checkedIn;
-    const idleConnections = Math.max(0, totalConnections - activeConnections);
-
-    // Reset wait queue after reporting (it's instantaneous)
-    const currentWaitQueue = poolStats.waitQueueSize;
-    poolStats.waitQueueSize = 0;
-
-    aggregator.updatePoolStats({
-      active: activeConnections,
-      idle: idleConnections,
-      waitQueueSize: currentWaitQueue,
-      total: totalConnections
-    });
-
-    debug(`MongoDB pool stats: active=${activeConnections}, idle=${idleConnections}, total=${totalConnections}, waitQueue=${currentWaitQueue}`);
-  } catch (err) {
-    debug(`Failed to collect pool stats: ${err.message}`);
-  }
-}
-
-/**
- * Instrument a MongoDB client or Mongoose connection
- *
- * @param {MongoClient|Mongoose} clientOrMongoose - MongoDB client or Mongoose instance
- */
-export function instrumentMongoDB(clientOrMongoose) {
-  if (!config.mongodb.enabled) {
-    debug('MongoDB instrumentation disabled');
-    return;
-  }
-
-  try {
-    let client;
-
-    // Check if it's Mongoose
-    if (clientOrMongoose?.connection?.getClient) {
-      client = clientOrMongoose.connection.getClient();
-      debug('Detected Mongoose, getting underlying MongoDB client');
-    } else if (clientOrMongoose?.getClient) {
-      // Mongoose connection object
-      client = clientOrMongoose.getClient();
-    } else if (typeof clientOrMongoose?.on === 'function') {
-      // Native MongoDB client
-      client = clientOrMongoose;
-    } else {
-      warn('Unable to instrument MongoDB: unrecognized client type');
-      return;
-    }
-
-    if (!client) {
-      warn('MongoDB client not available for instrumentation');
-      return;
-    }
-
-    // Store reference for pool stats
-    mongoClient = client;
-
-    // Attach command monitoring listeners
-    client.on('commandStarted', handleCommandStarted);
-    client.on('commandSucceeded', handleCommandSucceeded);
-    client.on('commandFailed', handleCommandFailed);
-
-    // Attach CMAP (Connection Pool Monitoring) event listeners
-    client.on('connectionPoolCreated', handleConnectionPoolCreated);
-    client.on('connectionCreated', handleConnectionCreated);
-    client.on('connectionClosed', handleConnectionClosed);
-    client.on('connectionCheckedOut', handleConnectionCheckedOut);
-    client.on('connectionCheckedIn', handleConnectionCheckedIn);
-    client.on('connectionCheckOutStarted', handleConnectionCheckOutStarted);
-    client.on('connectionCheckOutFailed', handleConnectionCheckOutFailed);
-
-    // Start pool stats collection
-    if (poolStatsInterval) {
-      clearInterval(poolStatsInterval);
-    }
-    poolStatsInterval = setInterval(collectPoolStats, config.mongodb.poolStatsInterval);
-
-    // Don't keep process alive just for pool stats
-    if (poolStatsInterval.unref) {
-      poolStatsInterval.unref();
-    }
-
-    debug('MongoDB instrumentation attached successfully');
-  } catch (err) {
-    warn(`Failed to instrument MongoDB: ${err.message}`);
-  }
-}
-
-/**
- * Auto-detect and instrument MongoDB
- * Called automatically during SDK initialization
- */
-export function autoInstrumentMongoDB() {
-  if (!config.mongodb.enabled) {
-    debug('MongoDB instrumentation disabled');
-    return;
-  }
-
-  // Try to detect mongoose
-  try {
-    // Dynamic import to avoid requiring mongoose as a dependency
-    const mongoose = globalThis.mongoose;
-    if (mongoose?.connection) {
-      // Wait for connection to be ready
-      if (mongoose.connection.readyState === 1) {
-        instrumentMongoDB(mongoose);
-      } else {
-        mongoose.connection.once('connected', () => {
-          instrumentMongoDB(mongoose);
-        });
-        debug('Waiting for Mongoose connection to instrument');
-      }
-      return;
-    }
-  } catch (e) {
-    // Mongoose not available
-  }
-
-  debug('No MongoDB client detected for auto-instrumentation. Use instrumentMongoDB() manually.');
-}
-
-/**
- * Stop MongoDB instrumentation
- */
-export function stopMongoDBInstrumentation() {
-  if (poolStatsInterval) {
-    clearInterval(poolStatsInterval);
-    poolStatsInterval = null;
-  }
-
-  if (mongoClient) {
-    // Remove command monitoring listeners
-    mongoClient.removeListener('commandStarted', handleCommandStarted);
-    mongoClient.removeListener('commandSucceeded', handleCommandSucceeded);
-    mongoClient.removeListener('commandFailed', handleCommandFailed);
-
-    // Remove CMAP listeners
-    mongoClient.removeListener('connectionPoolCreated', handleConnectionPoolCreated);
-    mongoClient.removeListener('connectionCreated', handleConnectionCreated);
-    mongoClient.removeListener('connectionClosed', handleConnectionClosed);
-    mongoClient.removeListener('connectionCheckedOut', handleConnectionCheckedOut);
-    mongoClient.removeListener('connectionCheckedIn', handleConnectionCheckedIn);
-    mongoClient.removeListener('connectionCheckOutStarted', handleConnectionCheckOutStarted);
-    mongoClient.removeListener('connectionCheckOutFailed', handleConnectionCheckOutFailed);
-
-    mongoClient = null;
-  }
-
-  // Reset pool stats
-  poolStats.totalCreated = 0;
-  poolStats.totalClosed = 0;
-  poolStats.checkedOut = 0;
-  poolStats.checkedIn = 0;
-  poolStats.waitQueueSize = 0;
-
-  pendingCommands.clear();
-  debug('MongoDB instrumentation stopped');
-}
-
-export default {
-  instrumentMongoDB,
-  autoInstrumentMongoDB,
-  stopMongoDBInstrumentation
-};
+/**
+ * MongoDB Instrumentation Module
+ *
+ * Hooks into MongoDB driver's command monitoring events to track:
+ * - Query operations (find, insert, update, delete, aggregate)
+ * - Latency and error rates per collection
+ * - Connection pool statistics
+ * - Slow query detection
+ *
+ * Uses MongoDB driver's built-in APM events (no monkey-patching):
+ * - commandStarted: Record start time
+ * - commandSucceeded: Calculate latency, record success
+ * - commandFailed: Record failure with error info
+ */
+
+import config, { debug, warn } from './config.js';
+import { getAggregator } from './aggregator.js';
+
+// Track pending commands by requestId
+const pendingCommands = new Map();
+
+// Track whether we've already instrumented to avoid double-attaching
+let isInstrumented = false;
+
+// Deferred detection timer (so we can clean it up on shutdown)
+let detectionTimer = null;
+
+// Track connection pool stats via CMAP events
+const poolStats = {
+  totalCreated: 0,
+  totalClosed: 0,
+  checkedOut: 0,
+  checkedIn: 0,
+  waitQueueSize: 0
+};
+
+// Operations we want to track (skip admin/internal commands)
+const TRACKED_OPERATIONS = new Set([
+  'find', 'findOne', 'findAndModify',
+  'insert', 'insertOne', 'insertMany',
+  'update', 'updateOne', 'updateMany',
+  'delete', 'deleteOne', 'deleteMany',
+  'aggregate', 'count', 'countDocuments', 'estimatedDocumentCount',
+  'distinct', 'mapReduce',
+  'createIndexes', 'dropIndexes',
+  'bulkWrite'
+]);
+
+// Commands to ignore (internal/admin)
+const IGNORED_COMMANDS = new Set([
+  'hello', 'ismaster', 'isMaster', 'buildInfo', 'getLastError',
+  'ping', 'serverStatus', 'replSetGetStatus', 'hostInfo',
+  'listCollections', 'listIndexes', 'collStats', 'dbStats',
+  'saslStart', 'saslContinue', 'getnonce', 'authenticate'
+]);
+
+let mongoClient = null;
+let poolStatsInterval = null;
+
+/**
+ * Extract collection name from command
+ */
+function getCollectionName(command) {
+  // Most commands have collection name as the value of the command key
+  const commandName = Object.keys(command)[0];
+  const value = command[commandName];
+
+  // For aggregate, the collection is the value
+  if (typeof value === 'string' && value.length > 0 && value !== '1') {
+    return value;
+  }
+
+  // Check common collection name fields
+  if (command.collection) return command.collection;
+  if (command.ns) {
+    const parts = command.ns.split('.');
+    return parts.length > 1 ? parts.slice(1).join('.') : parts[0];
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Normalize operation name
+ */
+function normalizeOperation(commandName) {
+  const name = commandName.toLowerCase();
+
+  // Group similar operations
+  if (name.includes('find')) return 'find';
+  if (name.includes('insert')) return 'insert';
+  if (name.includes('update')) return 'update';
+  if (name.includes('delete') || name.includes('remove')) return 'delete';
+  if (name === 'aggregate') return 'aggregate';
+  if (name.includes('count')) return 'count';
+  if (name.includes('index')) return 'index';
+
+  return name;
+}
+
+/**
+ * Handle command started event
+ */
+function handleCommandStarted(event) {
+  if (!config.mongodb.enabled) return;
+
+  const commandName = event.commandName;
+
+  // Skip ignored commands
+  if (IGNORED_COMMANDS.has(commandName)) {
+    return;
+  }
+
+  // Store start time for latency calculation
+  pendingCommands.set(event.requestId, {
+    startTime: process.hrtime.bigint(),
+    commandName,
+    collection: getCollectionName(event.command),
+    databaseName: event.databaseName
+  });
+
+  debug(`MongoDB command started: ${commandName} on ${event.databaseName}`);
+}
+
+/**
+ * Handle command succeeded event
+ */
+function handleCommandSucceeded(event) {
+  if (!config.mongodb.enabled) return;
+
+  const pending = pendingCommands.get(event.requestId);
+  if (!pending) return;
+
+  pendingCommands.delete(event.requestId);
+
+  // Calculate latency in milliseconds
+  const latencyNs = process.hrtime.bigint() - pending.startTime;
+  const latencyMs = Number(latencyNs) / 1e6;
+
+  // Record the operation
+  const aggregator = getAggregator();
+  const operation = normalizeOperation(pending.commandName);
+
+  aggregator.recordMongoOperation(
+    pending.collection,
+    operation,
+    latencyMs,
+    false // not an error
+  );
+
+  // Check for slow query
+  if (latencyMs > config.mongodb.slowQueryMs) {
+    aggregator.recordSlowQuery(
+      pending.collection,
+      operation,
+      latencyMs
+    );
+    debug(`Slow MongoDB query: ${operation} on ${pending.collection} took ${latencyMs.toFixed(2)}ms`);
+  }
+
+  debug(`MongoDB command succeeded: ${pending.commandName} (${latencyMs.toFixed(2)}ms)`);
+}
+
+/**
+ * Handle command failed event
+ */
+function handleCommandFailed(event) {
+  if (!config.mongodb.enabled) return;
+
+  const pending = pendingCommands.get(event.requestId);
+  if (!pending) return;
+
+  pendingCommands.delete(event.requestId);
+
+  // Calculate latency in milliseconds
+  const latencyNs = process.hrtime.bigint() - pending.startTime;
+  const latencyMs = Number(latencyNs) / 1e6;
+
+  // Record the failed operation
+  const aggregator = getAggregator();
+  const operation = normalizeOperation(pending.commandName);
+
+  aggregator.recordMongoOperation(
+    pending.collection,
+    operation,
+    latencyMs,
+    true // is an error
+  );
+
+  warn(`MongoDB command failed: ${pending.commandName} - ${event.failure?.message || 'Unknown error'}`);
+}
+
+/**
+ * CMAP Event Handlers for Connection Pool Monitoring
+ */
+function handleConnectionCreated(event) {
+  poolStats.totalCreated++;
+  debug(`MongoDB connection created (total: ${poolStats.totalCreated})`);
+}
+
+function handleConnectionClosed(event) {
+  poolStats.totalClosed++;
+  debug(`MongoDB connection closed (total closed: ${poolStats.totalClosed})`);
+}
+
+function handleConnectionCheckedOut(event) {
+  poolStats.checkedOut++;
+  debug(`MongoDB connection checked out (active: ${poolStats.checkedOut - poolStats.checkedIn})`);
+}
+
+function handleConnectionCheckedIn(event) {
+  poolStats.checkedIn++;
+  debug(`MongoDB connection checked in (active: ${poolStats.checkedOut - poolStats.checkedIn})`);
+}
+
+function handleConnectionCheckOutStarted(event) {
+  poolStats.waitQueueSize++;
+}
+
+function handleConnectionCheckOutFailed(event) {
+  poolStats.waitQueueSize = Math.max(0, poolStats.waitQueueSize - 1);
+}
+
+function handleConnectionPoolCreated(event) {
+  debug(`MongoDB connection pool created: ${event.address}`);
+}
+
+/**
+ * Collect connection pool statistics
+ * Now uses tracked CMAP events for accurate stats
+ */
+function collectPoolStats() {
+  if (!mongoClient || !config.mongodb.enabled) return;
+
+  try {
+    const aggregator = getAggregator();
+
+    // Calculate current pool state from tracked events
+    const totalConnections = poolStats.totalCreated - poolStats.totalClosed;
+    const activeConnections = poolStats.checkedOut - poolStats.checkedIn;
+    const idleConnections = Math.max(0, totalConnections - activeConnections);
+
+    // Reset wait queue after reporting (it's instantaneous)
+    const currentWaitQueue = poolStats.waitQueueSize;
+    poolStats.waitQueueSize = 0;
+
+    aggregator.updatePoolStats({
+      active: activeConnections,
+      idle: idleConnections,
+      waitQueueSize: currentWaitQueue,
+      total: totalConnections
+    });
+
+    debug(`MongoDB pool stats: active=${activeConnections}, idle=${idleConnections}, total=${totalConnections}, waitQueue=${currentWaitQueue}`);
+  } catch (err) {
+    debug(`Failed to collect pool stats: ${err.message}`);
+  }
+}
+
+/**
+ * Try to detect mongoose from Node.js module cache.
+ * Works for both require() and import usage since ESM modules
+ * also populate require.cache via the CJS interop layer.
+ */
+function tryDetectMongoose() {
+  try {
+    // Strategy 1: Scan require.cache for mongoose
+    const cache = require.cache || {};
+    const cacheKeys = Object.keys(cache);
+    const mongooseKey = cacheKeys.find(
+      k => /[\\/]mongoose[\\/](?:lib[\\/])?index\.js$/.test(k) &&
+           !k.includes('node_modules/mongoose/node_modules')
+    );
+    if (mongooseKey && cache[mongooseKey]?.exports) {
+      const mod = cache[mongooseKey].exports;
+      // Verify it's actually mongoose (has connection property)
+      if (mod.connection) {
+        debug('Detected mongoose via require.cache');
+        return mod;
+      }
+    }
+  } catch (e) {
+    // require.cache not available (unlikely in Node.js)
+  }
+
+  // Strategy 2: Fallback — check globalThis (in case user set it manually)
+  try {
+    if (globalThis.mongoose?.connection) {
+      debug('Detected mongoose via globalThis');
+      return globalThis.mongoose;
+    }
+  } catch (e) { /* not available */ }
+
+  return null;
+}
+
+/**
+ * Try to enable monitorCommands on a MongoDB client.
+ * MongoDB driver v4.0+ requires this option for command events to fire.
+ * Returns true if monitorCommands is (or was made) enabled.
+ */
+function ensureMonitorCommands(client) {
+  try {
+    // Check if already enabled
+    const alreadyEnabled =
+      client.options?.monitorCommands ||
+      client.s?.options?.monitorCommands;
+
+    if (alreadyEnabled) {
+      debug('monitorCommands already enabled');
+      return true;
+    }
+
+    // Try to enable it on the client options
+    let enabled = false;
+
+    if (client.options && typeof client.options === 'object') {
+      try {
+        client.options.monitorCommands = true;
+        enabled = true;
+      } catch (e) { /* frozen or read-only */ }
+    }
+
+    // Also try internal options (some driver versions store config here)
+    if (client.s?.options && typeof client.s.options === 'object') {
+      try {
+        client.s.options.monitorCommands = true;
+        enabled = true;
+      } catch (e) { /* frozen or read-only */ }
+    }
+
+    if (enabled) {
+      debug('Enabled monitorCommands on MongoDB client');
+      return true;
+    }
+
+    // Could not enable — warn prominently
+    warn(
+      'MongoDB client does not have monitorCommands enabled. ' +
+      'Command monitoring events will not fire. ' +
+      'For full MongoDB monitoring, connect with: mongoose.connect(uri, { monitorCommands: true })'
+    );
+    return false;
+  } catch (err) {
+    debug(`Error checking monitorCommands: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Attach instrumentation to a detected mongoose instance.
+ * Handles waiting for the connection to be ready.
+ */
+function attachToMongoose(mongoose) {
+  if (isInstrumented) {
+    debug('MongoDB already instrumented, skipping');
+    return;
+  }
+
+  if (mongoose.connection.readyState === 1) {
+    // Already connected
+    instrumentMongoDB(mongoose);
+  } else if (mongoose.connection.readyState === 2) {
+    // Connecting — wait for it
+    mongoose.connection.once('connected', () => {
+      instrumentMongoDB(mongoose);
+    });
+    debug('Waiting for Mongoose connection to complete before instrumenting');
+  } else {
+    // Not connected yet — listen for future connection
+    mongoose.connection.once('connected', () => {
+      instrumentMongoDB(mongoose);
+    });
+    debug('Mongoose not yet connecting, will instrument when connected');
+  }
+}
+
+/**
+ * Instrument a MongoDB client or Mongoose connection
+ *
+ * @param {MongoClient|Mongoose} clientOrMongoose - MongoDB client or Mongoose instance
+ */
+export function instrumentMongoDB(clientOrMongoose) {
+  if (!config.mongodb.enabled) {
+    debug('MongoDB instrumentation disabled');
+    return;
+  }
+
+  if (isInstrumented) {
+    debug('MongoDB already instrumented, skipping');
+    return;
+  }
+
+  try {
+    let client;
+
+    // Check if it's Mongoose
+    if (clientOrMongoose?.connection?.getClient) {
+      client = clientOrMongoose.connection.getClient();
+      debug('Detected Mongoose, getting underlying MongoDB client');
+    } else if (clientOrMongoose?.getClient) {
+      // Mongoose connection object
+      client = clientOrMongoose.getClient();
+    } else if (typeof clientOrMongoose?.on === 'function') {
+      // Native MongoDB client
+      client = clientOrMongoose;
+    } else {
+      warn('Unable to instrument MongoDB: unrecognized client type');
+      return;
+    }
+
+    if (!client) {
+      warn('MongoDB client not available for instrumentation');
+      return;
+    }
+
+    // Ensure monitorCommands is enabled (required for command events in driver v4+)
+    ensureMonitorCommands(client);
+
+    // Store reference for pool stats
+    mongoClient = client;
+    isInstrumented = true;
+
+    // Stop detection timer if still running
+    if (detectionTimer) {
+      clearInterval(detectionTimer);
+      detectionTimer = null;
+    }
+
+    // Attach command monitoring listeners
+    client.on('commandStarted', handleCommandStarted);
+    client.on('commandSucceeded', handleCommandSucceeded);
+    client.on('commandFailed', handleCommandFailed);
+
+    // Attach CMAP (Connection Pool Monitoring) event listeners
+    client.on('connectionPoolCreated', handleConnectionPoolCreated);
+    client.on('connectionCreated', handleConnectionCreated);
+    client.on('connectionClosed', handleConnectionClosed);
+    client.on('connectionCheckedOut', handleConnectionCheckedOut);
+    client.on('connectionCheckedIn', handleConnectionCheckedIn);
+    client.on('connectionCheckOutStarted', handleConnectionCheckOutStarted);
+    client.on('connectionCheckOutFailed', handleConnectionCheckOutFailed);
+
+    // Start pool stats collection
+    if (poolStatsInterval) {
+      clearInterval(poolStatsInterval);
+    }
+    poolStatsInterval = setInterval(collectPoolStats, config.mongodb.poolStatsInterval);
+
+    // Don't keep process alive just for pool stats
+    if (poolStatsInterval.unref) {
+      poolStatsInterval.unref();
+    }
+
+    debug('MongoDB instrumentation attached successfully');
+  } catch (err) {
+    warn(`Failed to instrument MongoDB: ${err.message}`);
+  }
+}
+
+/**
+ * Auto-detect and instrument MongoDB
+ * Called automatically during SDK initialization.
+ *
+ * Uses require.cache scanning to detect mongoose, with a deferred
+ * retry mechanism for cases where mongoose loads after the SDK.
+ */
+export function autoInstrumentMongoDB() {
+  if (!config.mongodb.enabled) {
+    debug('MongoDB instrumentation disabled');
+    return;
+  }
+
+  if (isInstrumented) {
+    debug('MongoDB already instrumented');
+    return;
+  }
+
+  // Try immediate detection
+  const mongoose = tryDetectMongoose();
+  if (mongoose) {
+    attachToMongoose(mongoose);
+    return;
+  }
+
+  // Deferred detection: retry periodically as the app boots up.
+  // Mongoose may not be loaded yet when the SDK initializes.
+  let attempts = 0;
+  const maxAttempts = 6;        // 6 retries
+  const retryInterval = 5000;   // every 5s → 30s total detection window
+
+  detectionTimer = setInterval(() => {
+    attempts++;
+
+    if (isInstrumented) {
+      // Instrumented via manual call while we were waiting
+      clearInterval(detectionTimer);
+      detectionTimer = null;
+      return;
+    }
+
+    const m = tryDetectMongoose();
+    if (m) {
+      clearInterval(detectionTimer);
+      detectionTimer = null;
+      attachToMongoose(m);
+      return;
+    }
+
+    if (attempts >= maxAttempts) {
+      clearInterval(detectionTimer);
+      detectionTimer = null;
+      warn(
+        'MongoDB not auto-detected after 30s. ' +
+        'For MongoDB monitoring, call: instrumentMongoDB(mongoose) after connecting.'
+      );
+    }
+  }, retryInterval);
+
+  // Don't keep process alive just for detection
+  if (detectionTimer.unref) {
+    detectionTimer.unref();
+  }
+
+  debug('MongoDB auto-detection started (will retry for 30s)');
+}
+
+/**
+ * Stop MongoDB instrumentation
+ */
+export function stopMongoDBInstrumentation() {
+  // Stop deferred detection timer
+  if (detectionTimer) {
+    clearInterval(detectionTimer);
+    detectionTimer = null;
+  }
+
+  if (poolStatsInterval) {
+    clearInterval(poolStatsInterval);
+    poolStatsInterval = null;
+  }
+
+  if (mongoClient) {
+    // Remove command monitoring listeners
+    mongoClient.removeListener('commandStarted', handleCommandStarted);
+    mongoClient.removeListener('commandSucceeded', handleCommandSucceeded);
+    mongoClient.removeListener('commandFailed', handleCommandFailed);
+
+    // Remove CMAP listeners
+    mongoClient.removeListener('connectionPoolCreated', handleConnectionPoolCreated);
+    mongoClient.removeListener('connectionCreated', handleConnectionCreated);
+    mongoClient.removeListener('connectionClosed', handleConnectionClosed);
+    mongoClient.removeListener('connectionCheckedOut', handleConnectionCheckedOut);
+    mongoClient.removeListener('connectionCheckedIn', handleConnectionCheckedIn);
+    mongoClient.removeListener('connectionCheckOutStarted', handleConnectionCheckOutStarted);
+    mongoClient.removeListener('connectionCheckOutFailed', handleConnectionCheckOutFailed);
+
+    mongoClient = null;
+  }
+
+  // Reset state
+  isInstrumented = false;
+
+  // Reset pool stats
+  poolStats.totalCreated = 0;
+  poolStats.totalClosed = 0;
+  poolStats.checkedOut = 0;
+  poolStats.checkedIn = 0;
+  poolStats.waitQueueSize = 0;
+
+  pendingCommands.clear();
+  debug('MongoDB instrumentation stopped');
+}
+
+export default {
+  instrumentMongoDB,
+  autoInstrumentMongoDB,
+  stopMongoDBInstrumentation
+};