# Add OpenTelemetry Tracing to an Express and Mongoose API

Yes. An agent adds the OpenTelemetry Node SDK with Express, HTTP, Mongoose and winston instrumentation to your API, loaded before Mongoose, with trace ids in logs.

[Run this on Rush](https://cloud.getrush.ai/run/add-opentelemetry/mongoose/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the process starts before it adds tracing, because instrumentation that loads after the modules it patches sees nothing. In an API like hagopj13/node-express-boilerplate, `src/index.js` requires `mongoose`, `./app` and the logger at the top, calls `mongoose.connect` and then `app.listen`, and installs `uncaughtException`, `unhandledRejection` and `SIGTERM` handlers that close the server. `src/app.js` stacks `morgan`, `helmet`, JSON parsing, `xss-clean`, `express-mongo-sanitize`, `compression`, `cors`, passport's JWT strategy, a rate limiter on `/v1/auth` in production, the `/v1` router and the `errorConverter` and `errorHandler` middlewares. `src/config/logger.js` builds a winston logger whose `printf` format prints only `level: message`, and `src/config/morgan.js` logs each request through it. `ecosystem.config.json` runs the app under pm2 with one instance; `yarn.lock` resolves `mongoose` to 5.13.20, `express` to 4.17.1 and `winston` to 3.3.3, and `package.json` has no OpenTelemetry package.

The agent adds `@opentelemetry/sdk-node`, `@opentelemetry/auto-instrumentations-node` and `@opentelemetry/exporter-trace-otlp-http`, and writes `src/config/tracing.js`, which builds a `NodeSDK` with a resource whose `service.name` comes from `OTEL_SERVICE_NAME` or the package name, an OTLP HTTP exporter that reads `OTEL_EXPORTER_OTLP_ENDPOINT`, and `getNodeAutoInstrumentations` with the `fs` instrumentation turned off because it is noisy and the rest left on. The bundle includes the HTTP, Express, MongoDB, Mongoose and winston instrumentations; the Mongoose one supports 5.9.7 through 9, which covers the locked 5.13.20, and names its spans `{operation} {collection}`, so a registration shows as `findOne users` followed by `save users` under the Express span for `POST /v1/auth/register`. The file starts the SDK at load and exports a `shutdown` that flushes pending spans.

To load it first, the agent uses Node's `--require` rather than editing import order: `ecosystem.config.json` gets `node_args` of `--require ./src/config/tracing.js`, `dev` in `package.json` passes the same flag to nodemon, and the `Dockerfile`'s command is unchanged because it goes through pm2. When `NODE_ENV` is `test`, `tracing.js` returns without starting, so the Jest suite, which runs with `-i --detectOpenHandles`, keeps no exporter handle open. The `SIGTERM` handler in `src/index.js` awaits `shutdown()` before closing the server. The winston instrumentation injects `trace_id`, `span_id` and `trace_flags` into each log record, so the agent extends the `printf` format in `logger.js` to print `trace_id` when present and leaves the format alone otherwise, which keeps morgan's request lines readable and searchable by trace.

Configuration follows the project's pattern: `OTEL_SERVICE_NAME` and `OTEL_EXPORTER_OTLP_ENDPOINT` join `.env.example` with a comment, and the Joi schema in `src/config/config.js` lists them as optional strings so they are documented beside `MONGODB_URL`, even though the schema's `.unknown()` would have let them through. To check the result the agent needs a MongoDB, so it installs MongoDB Community in its sandbox from the vendor's package repository, points `MONGODB_URL` at it, runs `yarn lint` and `yarn test`, then starts the app once with `OTEL_TRACES_EXPORTER=console`, registers and logs in a user, and keeps the printed span tree and the log lines that now carry a `trace_id`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add OpenTelemetry tracing to this Express and Mongoose API and open a pull request. Read package.json, yarn.lock for the resolved mongoose version, src/index.js, src/app.js, src/config/config.js, src/config/logger.js, src/config/morgan.js, src/models/user.model.js, src/services/auth.service.js, ecosystem.config.json, Dockerfile, docker-compose.yml, jest.config.js, tests/utils/setupTestDB.js and .env.example first. Add the Node SDK, the auto-instrumentations bundle and the OTLP HTTP trace exporter; write a tracing module that starts the SDK with a service name and endpoint from environment variables, disables the fs instrumentation, skips startup when NODE_ENV is test, and exports a shutdown that the SIGTERM handler awaits. Load it with --require through pm2's node_args and the dev script rather than by editing import order. Print trace_id in the winston format when the winston instrumentation sets it. Add the two variables to .env.example and the Joi schema as optional. Install MongoDB in your sandbox, run yarn lint and yarn test, start the app once with the console exporter, register and log in a user, and open a pull request with the span tree and the correlated log lines.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/config/tracing.js` and changes `package.json`, `yarn.lock`, `ecosystem.config.json`, `src/index.js`, `src/config/logger.js`, `src/config/config.js` and `.env.example`. Its description shows the console exporter's span tree for one registration, with the HTTP server span, the Express middleware and router spans, and the `findOne users` and `save users` Mongoose spans beneath them, next to the winston lines for the same request carrying the same `trace_id`, plus the lint and test output.

In production the SDK exports to whatever OTLP endpoint the environment names, and nothing is exported when the variable is unset, so a deployment without a collector runs as before. Each request becomes a trace whose Mongoose spans carry the collection, the operation and the database name, which is where slow queries show up first.

Before merging, a reviewer sets the real endpoint and any auth header the collector needs, decides whether to turn on `dbStatementSerializer` so Mongoose spans carry the query text, and checks that pm2 passes `node_args` in their deployment the way it does under `yarn start`.

## Run it on every service without tracing

A team with several Express services built from this boilerplate sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own entry point, lockfile and logger and adapts the same three pieces, and the key's `webhook_url` receives one `run.completed` per repository with the pull request in `result`.

Once traces flow, a useful recurring run is the one that reads them. An automation with a `schedule` trigger each morning starts a run that queries the collector for the slowest Mongoose spans of the last day and opens an issue with the collection, operation and the route above it; an automation run is not tied to a key and has its own `max_runs_per_hour` cap.

## Why run it on Rush?

Tracing a Mongoose app fails quietly when the SDK loads a line too late, when the test suite keeps an exporter open, or when the logger drops the trace id the instrumentation gave it. The agent reads the boot order, the pm2 config and the logger format in its own sandbox, chooses `--require` so the order cannot regress, and proves the result with a real registration against a real MongoDB whose span tree it pastes.

Every step stays with the run: the MongoDB install, lint, the Jest suite and the console exporter output, so the review is about endpoint and sampling choices rather than whether spans appear. Several services can be instrumented at once, each in its own sandbox.

## Frequently asked questions

### Why load the SDK with --require instead of importing it first in src/index.js?

A `require` at the top of `src/index.js` works until someone adds an import above it, and `mongoose` is imported on the first line today. `--require` through pm2's `node_args` and the dev script runs the tracing module before any application code, whatever the file order.

### Will the Jest tests keep passing?

Yes. The tracing module returns without starting when `NODE_ENV` is `test`, which `jest.config.js` sets, so no exporter or timer is left for `--detectOpenHandles` to report, and the integration tests run against the test database exactly as before.

### Does the Mongoose instrumentation support version 5?

It supports Mongoose from 5.9.7 up to but not including 10, and the lockfile resolves 5.13.20. Spans are named by operation and collection, such as `save users`, with the database and collection as attributes.

### What ends up in my logs?

The winston instrumentation adds `trace_id`, `span_id` and `trace_flags` to each record while a span is active. The agent prints `trace_id` in the existing `printf` format so a request's log lines and its trace can be found from each other.

## More Mongoose jobs

- [Add Optimistic Locking to a Mongoose API](https://getrush.ai/run/add-optimistic-locking/mongoose/)
- [Add Request ID Logging to an Express and Mongoose API](https://getrush.ai/run/add-request-id-logging/mongoose/)
- [Add Seed Data to a Mongoose App](https://getrush.ai/run/add-seed-data/mongoose/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to a NestJS Service](https://getrush.ai/run/add-opentelemetry/nestjs/)
- [Add OpenTelemetry Tracing to a Phoenix App](https://getrush.ai/run/add-opentelemetry/phoenix/)
- [Add OpenTelemetry Tracing to a Quarkus App](https://getrush.ai/run/add-opentelemetry/quarkus/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
