What the agent does
The agent reads the middleware chain before it adds to it, because where a timing middleware sits decides what it measures. In an API laid out like javieraviles/node-typescript-koa-rest, package.json is at version 1.8.0 with engines pinned to Node 14 and npm 6, a package-lock.json at lockfile version 1, and dependencies on koa, @koa/router, koa-jwt, koa-helmet, @koa/cors, koa-bodyparser, koa-swagger-decorator, typeorm with pg, winston, class-validator and cron; the scripts are build (lint, tsc, copy static assets), serve, test with Jest 26 through ts-jest, test:coverage, a Newman integration suite and a Locust load test. src/server.ts opens the TypeORM connection first, then builds the app: a Helmet content security policy, cors(), the winston request logger from src/logger.ts that times each request and logs METHOD url status ms at info, warn or error by status, bodyParser(), the unprotected router with GET / from src/controller/general.ts, the koa-jwt middleware with unless for the Swagger paths, the protected router with the user CRUD routes, a CronJob from src/cron.ts on the expression in config.ts, and app.listen(config.port). The Dockerfile is node:14-alpine and exposes 3000, docker-compose.yml runs postgres:10-alpine and Adminer, and .github/workflows/ci.yml builds and tests on pushes and pull requests to master with Node 12 before deploying to Heroku.
The metrics live in one new module, src/metrics.ts. It creates a Registry, calls collectDefaultMetrics on it for the event loop lag, heap, GC and open handle gauges, and defines one Histogram named http_request_duration_seconds with labels method, route and status_code and buckets suited to an API that answers in milliseconds, plus a Counter named cron_job_runs_total. The exported middleware starts a timer, awaits next(), and observes with the route label set to ctx._matchedRoute, the pattern @koa/router puts on the context, so /users/:id is one series rather than one per user id, and unmatched when no router claimed the request. It is registered in src/server.ts ahead of the winston logger, so it times everything the logger logs, including the 401s koa-jwt produces. The prom-client version is chosen from the line whose engines field still allows Node 14, because package.json and the Dockerfile pin it, and the lockfile is regenerated with the npm 6 that the engines field names so its version 1 format does not change under the team.
The endpoint is GET /metrics on the unprotected router, which answers with register.metrics() and sets ctx.type to register.contentType, so a Prometheus scraper reads it without a JWT. Because that puts process gauges on the public port, the middleware checks an optional METRICS_TOKEN from config.ts: when it is set, a request without a matching Authorization: Bearer is refused, and when it is unset the endpoint is open and the pull request says so. The /metrics route itself is excluded from the histogram so a scrape every fifteen seconds does not dominate the fastest bucket. The cron callback in src/cron.ts increments the counter beside its existing console.log, which gives one series that confirms the hourly job is running at all.
Tests follow the existing ones under tests/controller, which call the static controller methods with a stubbed context. The agent writes tests/metrics.test.ts with a fake ctx and next, asserts the histogram gains an observation with the matched route, that /metrics answers with the Prometheus content type, and that a wrong bearer is refused when the token is set. It runs npm run lint, which also runs tsc --noEmit, and npm test, and pastes their tails into the pull request, then starts the server against a PostgreSQL it brings up in its sandbox and curls /metrics to paste the first lines of the exposition.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Prometheus metrics to this Koa API with prom-client. Read package.json, package-lock.json, Dockerfile, docker-compose.yml, .github/workflows/ci.yml, src/server.ts, src/config.ts, src/logger.ts, src/cron.ts, both router files and the tests first. Pick a prom-client version whose engines allow the Node version pinned in package.json and the Dockerfile, and regenerate the lockfile with the npm version the engines field names. Write src/metrics.ts with a Registry, collectDefaultMetrics, a histogram http_request_duration_seconds with method, route and status_code labels where route is the matched router pattern or unmatched, and a counter cron_job_runs_total. Register the middleware before the request logger in src/server.ts and exclude the metrics path from the histogram. Serve GET /metrics on the unprotected router with the registry's content type, refusing requests without a matching bearer when METRICS_TOKEN is set in config.ts and open otherwise. Increment the counter in the cron callback. Write a Jest test with a stubbed context for the middleware, the endpoint and the token check, run npm run lint and npm test, start PostgreSQL in the sandbox, run the server and curl /metrics, and open a pull request with the test output and the first lines of the exposition. Do not change the CI workflow or the Heroku deploy.",
"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/metrics.ts and tests/metrics.test.ts, changes src/server.ts to register the middleware and the route, src/config.ts to read METRICS_TOKEN, src/cron.ts to count runs, .example.env to document the token, and package.json and package-lock.json for the new dependency. Its description pastes the tails of npm run lint and npm test from the sandbox and the first lines of a real /metrics response, with the default process gauges and the histogram after a few requests to / and /users.
The existing CI workflow runs its build and Jest steps on the pull request, so the reviewer sees the new test pass on a GitHub runner; the Heroku deploy jobs are unchanged and still run only on master. The description notes that /metrics is open unless METRICS_TOKEN is set, and that the winston log line and the histogram now measure the same requests from the same point in the chain.
Before merging, a reviewer sets the token for the deployed app, decides whether the Prometheus scraper reaches the app through the public port or a private one, and checks the histogram buckets against the latencies the Locust run already reports, since buckets that are all too wide or too narrow flatten the quantiles.
Run it on every Koa service
A team with several Node services sends this body once per repository from its own server, each a POST /o/{org}/sessions with that 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 chain: an Express service gets req.route.path as the route label, a service that already exposes /metrics from another library gets its registry merged rather than a second endpoint, and one on a current Node gets the current prom-client line.
Once the metrics exist, an alert on them is the next event. A Grafana contact point can send a webhook with a custom Authorization: Bearer header, so a rule on the p99 of http_request_duration_seconds can call a Rush webhook trigger directly with the trigger's secret, with an Idempotency-Key header on the trigger's URL made from the alert's fingerprint so a repeated notification does not start a second run. The automation's prompt asks for a read of the slow route's handler and a comment naming the likely cause.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A metrics middleware is small, and the mistakes are in placement and labels: a histogram registered after the JWT check never sees a 401, a route label built from ctx.path makes one series per user id, and a /metrics route that counts itself skews the fastest bucket. The agent reads the chain in src/server.ts and the router patterns first, places the middleware where the logger already is, and runs the server against a database in its own sandbox to read the exposition back.
The lint and test output and the real /metrics response stay with the run and are pasted into the pull request, so the review is of series the app produced. Several services get the same histogram at once, each with its own route labels and its own Node floor respected.
Frequently asked questions
Why is the route label the router pattern and not the URL?
Because GET /users/42 and GET /users/43 are the same handler, and a label per id would make a new series for every user. @koa/router sets ctx._matchedRoute to the pattern it matched, so the label is /users/:id, and requests no router claimed are labelled unmatched.
Is /metrics protected by the JWT middleware?
No. It is on the unprotected router, ahead of koa-jwt, so a scraper needs no token. When METRICS_TOKEN is set in the environment the endpoint requires that bearer instead; when it is unset the endpoint is open, and the pull request says so.
Will it work on Node 14?
Yes. The app pins Node 14 in engines and the Dockerfile, so the agent picks the prom-client line whose own engines still allows it and regenerates the version 1 lockfile with npm 6 rather than a newer npm that would rewrite its format.
Does this replace the winston request log?
No. The logger keeps writing one line per request, and the histogram sits one step ahead of it in the chain, so both see the same requests. The log answers what happened to one request; the histogram answers how the route behaves over time.