Registry / observability / opentelemetry-instrumentation-mongodb2

opentelemetry-instrumentation-mongodb2

library1.0.2jsnpmunverified

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.

observability database

npm install opentelemetry-instrumentation-mongodb2

github ↗package ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-INST

opentelemetry-instrumentation-mongodb2

observabilityjavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongoDBInstrumentation

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

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

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

MongoDBInstrumentation

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

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

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

MongoDBInstrumentationConfig

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

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

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

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());

Debug

Known issues

breakingThe 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.

affects: >=1.0.0

gotchaenhancedDatabaseReporting 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.

affects: >=1.0.0

deprecatedThe 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.

affects: >=1.0.0

gotchaInstrumentation 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.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module '@opentelemetry/instrumentation-mongodb'

Package not installed or version mismatch with peer dependencies.

fix

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

TypeError: MongoDBInstrumentation is not a constructor

Using default import instead of named import in CommonJS.

fix

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

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

Instrumentation not registered before creating MongoClient.

fix

Call registerInstrumentations() before creating the MongoClient instance.

Error: MongoClient must be connected before performing operations

Attempting to call methods on an unconnected client.

fix

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

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

@opentelemetry/apirequiredPeer dependency required for OpenTelemetry API types and trace/span creation.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/open-telemetry/opentelemetry-js-contrib ↗

packagehttps://www.npmjs.com/package/opentelemetry-instrumentation-mongodb2 ↗