mongoose-hydrate-instrumentation

OpenTelemetry instrumentation for the Mongoose hydration lifecycle.

The problem

Most Mongoose/MongoDB OTEL plugins trace at the query level — find, insert, update, and so on. That's useful, but it leaves out something that can quietly eat into your response times: document hydration.

Hydration is what happens after the query — Mongoose taking raw BSON/JSON results and turning them into full Document instances with virtuals, getters, subdocuments, and everything else. On large result sets or complex schemas, this cost adds up and is otherwise invisible in your traces.

This plugin patches that part of the lifecycle so those spans actually show up.

Requirements

• Node.js >= 16
• Mongoose >= 6.x
• @opentelemetry/api >= 1.x

Installation

npm install mongoose-hydrate-instrumentation

Usage

Register the instrumentation before your Mongoose models are loaded, alongside the rest of your OTEL setup.

With the Node SDK

import { NodeSDK } from '@opentelemetry/sdk-node';
import { MongooseHydrateInstrumentation } from 'mongoose-hydrate-instrumentation';

const sdk = new NodeSDK({
  instrumentations: [new MongooseHydrateInstrumentation()],
});

sdk.start();

Manual

import { MongooseHydrateInstrumentation } from 'mongoose-hydrate-instrumentation';

const instrumentation = new MongooseHydrateInstrumentation();
instrumentation.enable();

Via registerInstrumentations

import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { MongooseHydrateInstrumentation } from 'mongoose-hydrate-instrumentation';

registerInstrumentations({
  instrumentations: [new MongooseHydrateInstrumentation()],
});

Spans

| Span | Description | |---|---| | mongoose.document.init | Wraps new Document initialization from raw data |

Development

git clone https://github.com/Sasikumar3096/mongoose-hydrate-instrumentation.git
cd mongoose-hydrate-instrumentation
npm install
npm test
npm run build

Linting and formatting use Biome:

npx biome check .
npx biome format --write .

Related

• @opentelemetry/instrumentation-mongoose — the official plugin, if you need query-level tracing
• OpenTelemetry JS Contrib

License

MIT