Node.js (Express) Integration Guide

Integrating TraceMole into a standalone Express backend involves registering the OpenTelemetry NodeSDK hook, wrapping your MongoDB client instance, and starting the process with required preloads. Follow these steps to set it up:

Official Example Application

To see a fully configured backend with intentionally slow queries, you can clone and run our working demo app on GitHub: TraceMole Node.js Example App

1. Install Required Packages Install

Install the OpenTelemetry SDK packages, the MongoDB driver instrumentation, and the TraceMole explain listener helper inside your Node.js project folder:

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/auto-instrumentations-node @opentelemetry/instrumentation-mongodb @tracemole/nextjs-mongodb-explain mongodb dotenv

2. Configure OpenTelemetry (`instrumentation.js`) Create / Add

Create an `instrumentation.js` file at the root of your project to initialize the OTel NodeSDK before any other modules load:

require("dotenv").config();
const { NodeSDK } = require("@opentelemetry/sdk-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-http");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { MongoDBInstrumentation } = require("@opentelemetry/instrumentation-mongodb");

const apiKey = process.env.TRACE_MOLE_API_KEY;

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? "node-tracemole-example",
  traceExporter: new OTLPTraceExporter({
    url:
      process.env.TRACEMOLE_OTLP_TRACES_ENDPOINT ??
      "http://localhost:4318/v1/traces",
    headers: apiKey ? { "x-api-key": apiKey } : {},
  }),

  instrumentations: [
    getNodeAutoInstrumentations({
      // Disable default mongodb instrumentation bundled in auto-instrumentations
      "@opentelemetry/instrumentation-mongodb": { enabled: false },
    }),
    new MongoDBInstrumentation({ requireParentSpan: false }),
  ],
});

sdk.start();

3. Create MongoDB Connector (`db.js`) Create / Modify

Initialize your MongoClient with `monitorCommands: true` enabled and register the TraceMole query explain listener:

const { MongoClient } = require("mongodb");
const { registerTraceMoleListener } = require("@tracemole/nextjs-mongodb-explain");

if (!process.env.MONGODB_URI) {
  throw new Error('Invalid/Missing environment variable: "MONGODB_URI"');
}

const uri = process.env.MONGODB_URI;
const options = {
  monitorCommands: true, // required for command listener
};

const client = new MongoClient(uri, options);

// Register TraceMole listener to trace explain stats
registerTraceMoleListener(client, {
  slowThreshold: 50, // ms — explain queries slower than 50ms
});

const dbPromise = client.connect().then(() => client.db());

module.exports = { client, dbPromise };

4. Configure Environment Variables (`.env`) Modify Config

Add the TraceMole API Key and your MongoDB connection URL to your environment file:

TRACE_MOLE_API_KEY=your_api_key_here
TRACEMOLE_OTLP_TRACES_ENDPOINT=https://your-endpoint/v1/traces
MONGODB_URI=mongodb+srv://your_connection_string

5. Start the Server with Instrumentation Run Command

Run your Node.js application by preloading the `instrumentation.js` file. This guarantees that OTel auto-instrumentation wraps HTTP/DB modules before Express starts listening:

node --require ./instrumentation.js app.js