What the agent does
The agent reads how the process starts and what it talks to before adding tracing, because OpenTelemetry's instrumentations patch modules at require time and must load first. In an API laid out like javieraviles/node-typescript-koa-rest, src/server.ts opens a TypeORM 0.2 Postgres connection with createConnection, then builds a Koa 2.13 app with koa-helmet, @koa/cors, the Winston request logger from src/logger.ts, koa-bodyparser, an unprotected @koa/router, koa-jwt and a koa-swagger-decorator router for /users, starts the hourly CronJob from src/cron.ts and calls app.listen(config.port). package.json says Node 14 and npm 6, builds with tsc into dist/, starts with node dist/server.js, tests with Jest 26 and ts-jest, and the Dockerfile runs npm run start on node:14-alpine. The only observability today is the Winston line GET /users 200 12ms that src/logger.ts writes per request, with its level chosen from the status code.
It adds src/tracing.ts, which builds a NodeSDK with OTLPTraceExporter and a resource whose service name comes from OTEL_SERVICE_NAME, registers HttpInstrumentation, KoaInstrumentation, PgInstrumentation and WinstonInstrumentation, and starts it, with process.on("SIGTERM") calling sdk.shutdown() so the last spans flush. Node 14 rules out the current 2.x line of the SDK, which needs Node 18, so the agent pins the 1.x SDK and the matching 0.5x instrumentation packages and says so in package.json and the pull request. The import goes at the top of src/server.ts, above koa, typeorm and winston, since an instrumentation registered after a module is required patches nothing; the alternative of node -r ./dist/tracing.js dist/server.js in the serve script is written up as the option that keeps server.ts untouched.
PgInstrumentation works because TypeORM 0.2 drives the pg driver underneath, so each getManager().getRepository(User).find() in src/controller/user.ts becomes a pg.query child span with the statement, under the koa.router span for /users and the HTTP GET server span. WinstonInstrumentation injects trace_id and span_id into every record the middleware in src/logger.ts writes, so the existing access line can be joined to its trace with no change to the logger itself. The CronJob callback only logs today, so it gets no manual span; the agent notes where one would go when it does real work. koa-jwt refusals already answer 401 through the middleware chain, so they show as a server span with http.status_code 401 and no router span.
To prove it, the agent runs the real stack in its sandbox: Postgres from apt, npm ci, npm run build, a ConsoleSpanExporter selected by OTEL_TRACES_EXPORTER=console for the demo, then GET /, a POST /users with a valid JWT and a GET /users/1, and pastes the span tree each request produced, with the pg.query child under the router span and the Winston line carrying the same trace_id. It also runs npm run lint and npm test, adds tests/tracing.test.ts that asserts the SDK is configured with the four instrumentations and shuts down on SIGTERM, and adds OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME and OTEL_TRACES_EXPORTER to .example.env and README.md.
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 Koa API. Read package.json, Dockerfile, docker-compose.yml, .example.env, README.md, src/server.ts, src/config.ts, src/logger.ts, src/cron.ts, src/controller/user.ts, src/protectedRoutes.ts, src/unprotectedRoutes.ts and tests/controller/user.test.ts first. Write src/tracing.ts that starts a NodeSDK with an OTLP trace exporter and a service name from OTEL_SERVICE_NAME, with the HTTP, Koa, pg and Winston instrumentations, and shuts down on SIGTERM; because the project runs on Node 14, pin the 1.x SDK and matching instrumentation versions and say why. Import it first in src/server.ts, before koa, typeorm and winston, and explain the node -r alternative in the pull request. Add OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME and OTEL_TRACES_EXPORTER to .example.env and README.md. In your sandbox install Postgres, build, start the server with the console exporter, send GET /, POST /users with a valid JWT and GET /users/1, and paste each request's span tree and the Winston access line with its trace_id into the pull request. Add a Jest test for the tracing module in the style of the existing tests. Run lint, tests and build. Change no route, middleware order or response.",
"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/tracing.ts and tests/tracing.test.ts, adds one import line at the top of src/server.ts, pins the OpenTelemetry packages in package.json and package-lock.json, and documents three variables in .example.env and README.md. Its description shows the span tree for each of the three requests, the pg.query spans with their SQL under the /users router span, the Winston line with its trace_id, and the Jest, lint and build results.
Routes, middleware order, the JWT check and the responses are unchanged, and the Dockerfile needs no edit because the import is in the entry point. With no OTEL_EXPORTER_OTLP_ENDPOINT set the SDK uses the OTLP default of localhost, so a deploy without a collector logs export failures rather than breaking requests, which the description points out.
Before merging, a reviewer sets the endpoint for their collector, decides whether the hourly cron job should carry a span once it does real work, and checks that the pinned 1.x packages match the Node 14 runtime in engines and the Docker image. Moving to the 2.x SDK is tied to a Node upgrade and is left as its own change.
Run it on every service without tracing
An engineer who was asked for traces before the next incident starts this from the terminal with this body and carries on. The run reads the real entry point, the ORM and the logger, so the instrumentation list and the version pins match this service's Node 14 and TypeORM 0.2 rather than a template written for the newest SDK.
Send a request_id, a UUID, with the body so a retried start returns the run it already began. The pull request link is on the run's GET /o/{org}/sessions/{id} answer once it is open, and a key with a webhook_url hears run.completed when the turn ends. A team with several Node services sends one body per repository; an Express service in the same batch gets the Express instrumentation in place of Koa's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The usual failure with OpenTelemetry in Node is silent: the SDK starts after the HTTP module was already required and no spans appear, or the SDK version needs a newer Node than the one in engines and the process fails at start. The agent catches both in its own sandbox by running the built server on the project's Node and reading the spans off the console exporter, so the pull request shows real span trees instead of a claim that tracing is on.
Every command and its output stays on the run, including the Postgres install, the build and the three requests, so the reviewer can see which spans exist and what they carry before deciding on a collector. Several services can be instrumented at once, each in its own sandbox, and nothing ships until a person reads the diff.
Frequently asked questions
Why pin the 1.x SDK instead of the current one?
package.json says node 14 and the image is node:14-alpine. The 2.x OpenTelemetry JavaScript SDK requires Node 18 or later, so on this runtime it would not start. The 1.x SDK and the instrumentation versions released alongside it support Node 14, and the pull request names the exact versions so the upgrade can follow a Node upgrade.
Why must the import be first in server.ts?
The HTTP, Koa, pg and Winston instrumentations work by patching those modules when they are first required. src/server.ts imports koa, winston and typeorm at the top, so a tracing import placed below them would patch nothing and produce no spans. Putting import "./tracing" on the first line, or preloading dist/tracing.js with node -r, makes the patches land before the modules load.
Do TypeORM queries show up?
Yes, as pg.query spans. TypeORM 0.2 uses the pg driver for the Postgres connection in src/server.ts, and PgInstrumentation wraps that driver, so each repository call in src/controller/user.ts becomes a child span with the SQL statement under the request's router span. There is no TypeORM-specific instrumentation involved.
How do the Winston access lines connect to traces?
WinstonInstrumentation adds trace_id, span_id and trace_flags to each log record written inside a request, including the GET /users 200 12ms line the middleware in src/logger.ts writes, without changing the logger. A log search for a trace id then finds the access line, and the pull request shows one such line beside its span tree.
What happens if no collector is running?
Requests are served as before. The OTLP exporter batches spans and logs an export error when the endpoint does not answer, which the agent shows in the sandbox by running once without a collector. The console exporter, selected with OTEL_TRACES_EXPORTER=console, is what the demo in the pull request uses; a deploy sets OTEL_EXPORTER_OTLP_ENDPOINT to its collector.