# Add Prometheus Metrics to a Koa API

Yes. An agent adds prom-client to your Koa app with a request duration histogram per matched route, a /metrics endpoint and default Node metrics, and opens a PR.

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

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

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

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

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

## More Koa jobs

- [Add Rate Limiting to a Koa App](https://getrush.ai/run/add-rate-limiting/koa/)
- [Add Request ID Logging to a Koa App](https://getrush.ai/run/add-request-id-logging/koa/)
- [Add Request Timeouts to a Koa App](https://getrush.ai/run/add-request-timeouts/koa/)

## The same job on other stacks

- [Add Prometheus Metrics to a Ktor Server](https://getrush.ai/run/add-prometheus-metrics/ktor/)
- [Add Prometheus Metrics to a Leptos App](https://getrush.ai/run/add-prometheus-metrics/leptos/)
- [Add Prometheus Metrics to a Litestar App](https://getrush.ai/run/add-prometheus-metrics/litestar/)

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