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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.