autotel-mongoose

OpenTelemetry instrumentation for Mongoose with stable semantic conventions, db.query.text capture, and default PII redaction.

What It Adds

• Captures db.query.text by default using JSON.stringify
• Redacts PII by default using Autotel's 'default' redactor preset
• Supports custom dbStatementSerializer functions with the same payload shape as the OpenTelemetry MongoDB plugin
• Uses stable semantic conventions only:
  • db.system.name
  • db.operation.name
  • db.collection.name
  • db.namespace
  • db.query.text
  • server.address
  • server.port
• Uses stable span names like find users

Installation

Install autotel-mongoose, autotel, and mongoose:

npm install autotel autotel-mongoose mongoose

This package supports Mongoose 8+.

Basic Usage

import mongoose from 'mongoose';
import { init } from 'autotel';
import { instrumentMongoose } from 'autotel-mongoose';

init({
  service: 'my-app',
  endpoint: 'http://localhost:4318',
});

instrumentMongoose(mongoose, {
  dbName: 'myapp',
});

const userSchema = new mongoose.Schema({
  name: String,
  email: String,
});

const User = mongoose.model('User', userSchema);

await mongoose.connect(process.env.MONGODB_URI!);
await User.findOne({ email: '[email protected]' }).exec();

Hook Instrumentation

Schema hook instrumentation is optional and disabled by default.

If you enable it, call instrumentMongoose() before defining schemas so pre and post hooks can be wrapped:

import mongoose from 'mongoose';
import { instrumentMongoose } from 'autotel-mongoose';

instrumentMongoose(mongoose, {
  instrumentHooks: true,
});

const userSchema = new mongoose.Schema({
  name: String,
});

userSchema.pre('save', async function () {
  this.set('name', this.get('name')?.trim());
});

Configuration

import type { InstrumentMongooseConfig } from 'autotel-mongoose';

const config: InstrumentMongooseConfig = {
  dbName: 'myapp',
  peerName: 'mongodb.internal',
  peerPort: 27017,
  tracerName: 'autotel-mongoose',
  captureCollectionName: true,
  instrumentHooks: false,
  dbStatementSerializer: false,
  statementRedactor: 'default',
};

Statement Capture

By default, this package serializes query payloads into db.query.text and redacts sensitive values before they are added to the span.

You can disable statement capture entirely:

instrumentMongoose(mongoose, {
  dbStatementSerializer: false,
});

You can also provide a custom serializer:

instrumentMongoose(mongoose, {
  dbStatementSerializer(operation, payload) {
    return JSON.stringify({
      operation,
      condition: payload.condition,
      updates: payload.updates,
    });
  },
});

Redaction

PII redaction is enabled by default through Autotel's 'default' preset.

You can provide a custom redactor config or disable redaction:

instrumentMongoose(mongoose, {
  statementRedactor: false,
});

Exported API

• instrumentMongoose(mongoose, config?)
• InstrumentMongooseConfig
• SerializerPayload

Notes

• Query and aggregate operations are traced automatically
• Instance methods like save() and deleteOne() are traced
• Static methods like create(), insertMany(), aggregate(), and bulkWrite() are traced
• Hook spans use SpanKind.INTERNAL

License

MIT