mirror of
https://github.com/zoriya/drizzle-otel.git
synced 2025-12-06 00:46:09 +00:00
74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# @kubiks/otel-mongodb
|
|
|
|
OpenTelemetry instrumentation for the [MongoDB Node.js driver](https://www.mongodb.com/docs/drivers/node/current/).
|
|
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
|
|
|
|
```bash
|
|
npm install @kubiks/otel-mongodb
|
|
# or
|
|
pnpm add @kubiks/otel-mongodb
|
|
```
|
|
|
|
**Peer Dependencies:** `@opentelemetry/api` >= 1.9.0, `mongodb` >= 5.0.0
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
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
|