@kubiks/otel-mongodb

OpenTelemetry instrumentation for the MongoDB Node.js driver. Capture spans for every MongoDB operation, enrich them with query metadata, and monitor database performance from your traces.

Visualize your MongoDB operations with detailed span information including collection names, operation types, and execution metrics.

Installation

npm install @kubiks/otel-mongodb
# or
pnpm add @kubiks/otel-mongodb

Peer Dependencies: @opentelemetry/api >= 1.9.0, mongodb >= 5.0.0

Quick Start

import { MongoClient } from "mongodb";
import { instrumentMongoClient } from "@kubiks/otel-mongodb";

const client = new MongoClient(process.env.MONGODB_URI!);
await client.connect();

instrumentMongoClient(client, {
  captureFilters: true,
  peerName: "mongodb.example.com",
  peerPort: 27017,
});

const db = client.db("myapp");
const users = db.collection("users");
const user = await users.findOne({ email: "[email protected]" });

instrumentMongoClient wraps the client you already use — no configuration changes needed. Every database operation creates a client span with useful attributes.

What Gets Traced

This instrumentation automatically traces all major MongoDB operations including find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, aggregate, countDocuments, and atomic operations like findOneAndUpdate.

Span Attributes

Each span includes:

| Attribute | Description | Example | | --------------------------- | ------------------------------------- | ----------------------- | | db.system | Constant value mongodb | mongodb | | db.operation | MongoDB operation type | findOne, insertMany | | db.mongodb.collection | Collection name | users | | db.name | Database name | myapp | | net.peer.name | MongoDB server hostname | mongodb.example.com | | net.peer.port | MongoDB server port | 27017 | | mongodb.filter | Query filter (when enabled) | {"status":"active"} | | mongodb.result_count | Number of documents returned | 42 | | mongodb.inserted_count | Number of documents inserted | 5 | | mongodb.matched_count | Number of documents matched (updates) | 10 | | mongodb.modified_count | Number of documents modified | 8 | | mongodb.deleted_count | Number of documents deleted | 15 | | mongodb.execution_time_ms | Query execution time (when enabled) | 42.5 | | mongodb.pipeline | Aggregation pipeline | [{"$match":...}] |

The instrumentation captures query metadata to help with debugging and monitoring, while optionally capturing filters based on your security requirements.

License

MIT