drizzle-otel/packages/otel-mongodb/README.md

@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: "user@example.com" });

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