Node.js + MongoDB + TraceMole Example

An Express API wired for TraceMole query profiling. The routes run intentionally inefficient MongoDB queries (collection scans, N+1 patterns, regex scans) so you can see them flagged in the TraceMole dashboard.

Companion to the Next.js TraceMole example.

What you get

• REST API for a NYC restaurant directory
• Sample data seeding (~160 documents into restaurants_demo.restaurants)
• OpenTelemetry tracing with MongoDB driver instrumentation
• MongoDB explain stats on spans via @tracemole/nextjs-mongodb-explain

Prerequisites

Requirement	Notes
Node.js	LTS or current release
MongoDB	MongoDB Atlas free tier works
TraceMole account	Sign up for an API key and OTLP ingest URL

Quick start

1. Install dependencies

npm install

2. Configure environment variables

cp .env.example .env

Edit .env:

MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
TRACE_MOLE_API_KEY=<your-trace-mole-api-key>
TRACEMOLE_OTLP_TRACES_ENDPOINT=<your-trace-mole-otlp-endpoint>

Variable	Required	Description
MONGODB_URI	Yes	MongoDB connection string
TRACE_MOLE_API_KEY	Yes	API key from your TraceMole project
TRACEMOLE_OTLP_TRACES_ENDPOINT	Yes	OTLP traces URL (e.g. https://…/v1/traces)
OTEL_SERVICE_NAME	No	Service name in traces (default: node-tracemole-example)
PORT	No	HTTP port (default: 3000)

Optional: disable explain queries in production:

TRACE_MOLE_MONGO_EXPLAIN=0

3. Start the server

npm start

Open http://localhost:3000 for route documentation.

4. Load sample data

curl -X POST http://localhost:3000/api/seed

5. Generate traces

Hit the intentionally slow endpoints:

Action	Request	Query behavior
List restaurants	GET /api/restaurants	Sort on unindexed field + N+1 cuisine lookups
Dashboard stats	GET /api/stats	Full collection scan + per-borough count loop
Browse / search	GET /api/browse?borough=Queens&name=moon	Loads entire collection, filters in Node
Add restaurant	POST /api/restaurants	Regex collection scans after insert

curl http://localhost:3000/api/restaurants
curl http://localhost:3000/api/stats
curl "http://localhost:3000/api/browse?borough=Queens&name=moon"
curl -X POST http://localhost:3000/api/restaurants \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Diner","borough":"Manhattan","cuisine":"American"}'

Then open the TraceMole dashboard to inspect explain plans, scan types, and slow operations.

How tracing is wired

OpenTelemetry (instrumentation.js)

The app starts with node --require ./instrumentation.js app.js. On startup, instrumentation:

1. Starts the OpenTelemetry Node SDK
2. Exports traces to TRACEMOLE_OTLP_TRACES_ENDPOINT with an x-api-key header
3. Instruments MongoDB via @opentelemetry/instrumentation-mongodb

If TRACEMOLE_OTLP_TRACES_ENDPOINT is unset, traces fall back to http://localhost:4318/v1/traces.

MongoDB explain listener (lib/mongodb.js)

The MongoDB client registers TraceMole's command listener:

registerTraceMoleListener(client, { slowThreshold: 50 });

Queries slower than 50ms get an explain plan attached to the active span as db.mongodb.explain.* attributes.

Project structure

├── app.js                 # Express server
├── instrumentation.js     # OpenTelemetry + TraceMole export
├── lib/
│   ├── mongodb.js         # MongoDB client + explain listener
│   ├── db.js              # Collection helpers
│   ├── queries.js         # Intentionally bad query patterns
│   ├── seed-data.js       # Base restaurant documents
│   └── seed-build.js      # Expands seed to 160 docs
└── routes/
    ├── restaurants.js     # List + create
    ├── browse.js          # Filtered search
    ├── stats.js           # Dashboard counts
    └── seed.js            # Load / clear sample data

Troubleshooting

Missing required environment variable: "MONGODB_URI" Add MONGODB_URI to .env and restart the server.

No traces in TraceMole

• Confirm TRACE_MOLE_API_KEY and TRACEMOLE_OTLP_TRACES_ENDPOINT are set in .env
• Restart the server after editing env vars
• Hit the API endpoints to generate traffic
• Check Atlas network access allows your IP

Empty restaurant list Run curl -X POST http://localhost:3000/api/seed or add a restaurant via POST /api/restaurants.

Related links

• TraceMole
• @tracemole/nextjs-mongodb-explain on npm
• Next.js TraceMole example
• MongoDB Node.js driver