# Add OpenTelemetry Tracing to a Koa API

Yes. An agent adds OpenTelemetry to your Koa API: a bootstrap loaded before Koa, HTTP, router, Postgres and Winston instrumentation, an OTLP exporter, real spans.

[Run this on Rush](https://cloud.getrush.ai/run/add-opentelemetry/koa/). 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 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`

```json
{
  "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"
    }
  ]
}
```

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/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.

## 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.

## More Koa jobs

- [Add Pagination to a Koa REST API](https://getrush.ai/run/add-pagination/koa/)
- [Add Prometheus Metrics to a Koa API](https://getrush.ai/run/add-prometheus-metrics/koa/)
- [Add Rate Limiting to a Koa App](https://getrush.ai/run/add-rate-limiting/koa/)

## The same job on other stacks

- [Add OpenTelemetry Tracing to a Ktor Server](https://getrush.ai/run/add-opentelemetry/ktor/)
- [Add OpenTelemetry Tracing to a Litestar App](https://getrush.ai/run/add-opentelemetry/litestar/)
- [Add OpenTelemetry Tracing to a Medusa Backend](https://getrush.ai/run/add-opentelemetry/medusa/)

## 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/)
