{"id":27209,"library":"opentelemetry-instrumentation-mongodb2","title":"OpenTelemetry MongoDB Instrumentation","description":"OpenTelemetry instrumentation for the `mongodb` Node.js driver that automatically captures trace data for database operations. Current stable version: 1.0.2. Released as part of the opentelemetry-js-contrib monorepo with periodic updates aligned with OpenTelemetry JS API/SDK releases. Key differentiators: supports mongodb versions >=3.3.0 <7, offers enhanced database reporting via `enhancedDatabaseReporting` option, custom response hooks, and db statement serialization. Compatible with OpenTelemetry JS API 1.3+ and Semantic Conventions 1.22+. Typically used with @opentelemetry/sdk-trace-node or bundled in auto-instrumentations-node.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-js-contrib","tags":["javascript","mongodb","nodejs","opentelemetry","plugin","profiling","tracing","typescript"],"install":[{"cmd":"npm install opentelemetry-instrumentation-mongodb2","lang":"bash","label":"npm"},{"cmd":"yarn add opentelemetry-instrumentation-mongodb2","lang":"bash","label":"yarn"},{"cmd":"pnpm add opentelemetry-instrumentation-mongodb2","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for OpenTelemetry API types and trace/span creation.","package":"@opentelemetry/api","optional":false}],"imports":[{"note":"This package is CJS-only and does not ship ESM. Use require().","wrong":"import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb';","symbol":"MongoDBInstrumentation","correct":"const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');"},{"note":"Commonjs require must destructure the named export, not assign the whole module.","wrong":"const MongoDBInstrumentation = require('@opentelemetry/instrumentation-mongodb');","symbol":"MongoDBInstrumentation","correct":"const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');"},{"note":"Type-only import in TypeScript to avoid runtime value import. Not available as a runtime export.","wrong":"const { MongoDBInstrumentationConfig } = require('@opentelemetry/instrumentation-mongodb');","symbol":"MongoDBInstrumentationConfig","correct":"import type { MongoDBInstrumentationConfig } from '@opentelemetry/instrumentation-mongodb';"}],"quickstart":{"code":"const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');\nconst { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');\nconst { registerInstrumentations } = require('@opentelemetry/instrumentation');\n\nconst provider = new NodeTracerProvider();\nprovider.register();\n\nregisterInstrumentations({\n  instrumentations: [\n    new MongoDBInstrumentation({\n      enhancedDatabaseReporting: process.env.ENHANCED_REPORTING === 'true' || false,\n    }),\n  ],\n});\n\nconst { MongoClient } = require('mongodb');\nconst client = new MongoClient('mongodb://localhost:27017');\nclient.connect().then(() => {\n  const db = client.db('test');\n  return db.collection('users').findOne({ name: 'Alice' });\n}).then(() => client.close());","lang":"javascript","description":"Shows how to instrument mongodb operations with OpenTelemetry using MongoDBInstrumentation and registerInstrumentations."},"warnings":[{"fix":"Use require() instead of import. Set type: 'commonjs' in package.json or use dynamic import if needed.","message":"The package is CJS-only and does not support ESM imports; using import will fail at runtime.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Set enhancedDatabaseReporting to 'true' or 'false' as a string.","message":"enhancedDatabaseReporting option is of type string, not boolean. Passing a boolean will be coerced to a string or ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your OpenTelemetry collector or backend to handle both old and new attribute names, or pin to an older semantic conventions version.","message":"The net.peer.name and net.peer.port attributes are deprecated in favor of server.address and server.port in newer semantic conventions.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Check your mongodb dependency version. If using mongodb@7, this instrumentation will not apply; consider using @opentelemetry/instrumentation-mongodb@latest.","message":"Instrumentation does not automatically detect the mongodb module version; you must ensure mongodb version is between 3.3.0 and 6.x inclusive (as of this writing).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run npm install @opentelemetry/instrumentation-mongodb @opentelemetry/api@^1.3.0","cause":"Package not installed or version mismatch with peer dependencies.","error":"Cannot find module '@opentelemetry/instrumentation-mongodb'"},{"fix":"Use const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');","cause":"Using default import instead of named import in CommonJS.","error":"TypeError: MongoDBInstrumentation is not a constructor"},{"fix":"Call registerInstrumentations() before creating the MongoClient instance.","cause":"Instrumentation not registered before creating MongoClient.","error":"TypeError: Cannot read properties of undefined (reading 'findOne')"},{"fix":"Ensure await client.connect() resolves before using db/collection methods.","cause":"Attempting to call methods on an unconnected client.","error":"Error: MongoClient must be connected before performing operations"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}