OpenTelemetry MongoDB Instrumentation

1.0.2 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Cannot find module '@opentelemetry/instrumentation-mongodb' ↓

cause Package not installed or version mismatch with peer dependencies.

fix

Run npm install @opentelemetry/instrumentation-mongodb @opentelemetry/api@^1.3.0

error TypeError: MongoDBInstrumentation is not a constructor ↓

cause Using default import instead of named import in CommonJS.

fix

Use const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');

error TypeError: Cannot read properties of undefined (reading 'findOne') ↓

cause Instrumentation not registered before creating MongoClient.

fix

Call registerInstrumentations() before creating the MongoClient instance.

error Error: MongoClient must be connected before performing operations ↓

cause Attempting to call methods on an unconnected client.

fix

Ensure await client.connect() resolves before using db/collection methods.

Warnings

breaking The package is CJS-only and does not support ESM imports; using import will fail at runtime. ↓

fix Use require() instead of import. Set type: 'commonjs' in package.json or use dynamic import if needed.

gotcha enhancedDatabaseReporting option is of type string, not boolean. Passing a boolean will be coerced to a string or ignored. ↓

fix Set enhancedDatabaseReporting to 'true' or 'false' as a string.

deprecated The net.peer.name and net.peer.port attributes are deprecated in favor of server.address and server.port in newer semantic conventions. ↓

fix Update your OpenTelemetry collector or backend to handle both old and new attribute names, or pin to an older semantic conventions version.

gotcha 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). ↓

fix Check your mongodb dependency version. If using mongodb@7, this instrumentation will not apply; consider using @opentelemetry/instrumentation-mongodb@latest.

Install

npm install opentelemetry-instrumentation-mongodb2

yarn add opentelemetry-instrumentation-mongodb2

pnpm add opentelemetry-instrumentation-mongodb2

Imports

MongoDBInstrumentation

wrong

import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb';

correct

const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');

This package is CJS-only and does not ship ESM. Use require().

MongoDBInstrumentation

wrong

const MongoDBInstrumentation = require('@opentelemetry/instrumentation-mongodb');

correct

const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');

Commonjs require must destructure the named export, not assign the whole module.

MongoDBInstrumentationConfig

wrong

const { MongoDBInstrumentationConfig } = require('@opentelemetry/instrumentation-mongodb');

correct

import type { MongoDBInstrumentationConfig } from '@opentelemetry/instrumentation-mongodb';

Type-only import in TypeScript to avoid runtime value import. Not available as a runtime export.

Quickstart

Shows how to instrument mongodb operations with OpenTelemetry using MongoDBInstrumentation and registerInstrumentations.

const { MongoDBInstrumentation } = require('@opentelemetry/instrumentation-mongodb');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new MongoDBInstrumentation({
      enhancedDatabaseReporting: process.env.ENHANCED_REPORTING === 'true' || false,
    }),
  ],
});

const { MongoClient } = require('mongodb');
const client = new MongoClient('mongodb://localhost:27017');
client.connect().then(() => {
  const db = client.db('test');
  return db.collection('users').findOne({ name: 'Alice' });
}).then(() => client.close());