# Add Health Checks to an Echo API

Yes. An agent adds /healthz and /readyz to your Echo API, with readiness pinging the database through gorm, a handler test and a Docker HEALTHCHECK, and opens a PR.

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

## What the agent does

The agent starts from how the server is wired, because a health route has to sit outside the groups that need a token. In an Echo project like xesina/golang-echo-realworld-example-app, `main.go` builds the router with `router.New()`, mounts Swagger at `/swagger/*`, opens SQLite with `db.New()`, runs `db.AutoMigrate`, and hands two stores to `handler.NewHandler` before `h.Register(v1)` fills the `/api` group. `router/router.go` sets the log level to debug, adds `RemoveTrailingSlash`, `Logger` and a permissive CORS config, and installs a `go-playground/validator` instance. `handler/routes.go` puts `/api/user`, `/api/profiles` and most of `/api/articles` behind the JWT middleware. `go.mod` pins `labstack/echo/v4` at v4.1.16, `jinzhu/gorm` at v1.9.8 and Go 1.18, and there is no health route anywhere.

It then decides what the two probes should mean. `GET /healthz` is liveness: the process is up and Echo is serving, so it answers `200` with `{"status":"ok"}` and touches nothing else. `GET /readyz` is readiness: it calls `PingContext` on the `*sql.DB` that gorm v1 exposes through `d.DB()`, with a two second timeout, and answers `200` with `{"status":"ok","database":"ok"}` or `503` with the failing check named. The agent writes both in a new `health` package whose constructor takes the `*sql.DB`, because `handler.Handler` holds only the two stores and has no connection to ping, and registers them on the root `*echo.Echo` in `main.go` rather than on the `/api` group, so they stay outside the JWT groups, the Swagger prefix and the `docs/` that `swag` generates.

Probes arrive every few seconds, and `router.New()` logs every request at debug level, so the agent gives `middleware.LoggerWithConfig` a `Skipper` that drops `/healthz` and `/readyz` from the access log. The `Dockerfile` already builds a static binary into an Alpine image and exposes 8585, so the agent adds a `HEALTHCHECK` that runs busybox `wget -qO- http://127.0.0.1:8585/readyz` on an interval, which is the one place the server's `127.0.0.1:8585` bind address is reachable from. The pull request notes that the loopback bind means a published port still reaches nothing from the host, and leaves that change to a reviewer because it is not what was asked.

The test goes in `health/health_test.go` rather than beside `handler/handler_test.go`, whose `TestMain` creates `../realworld_test.db` and drops it after the run. The new test opens its own SQLite database through gorm, builds the handler, and asserts `/readyz` answers `200` with the connection open and `503` after `d.Close()`, using `httptest.NewRequest`, `e.NewContext` and `testify/assert` the way `handler/user_test.go` does. The agent then runs what `.github/workflows/go.yml` runs, `go build -v ./...` and `go test -v ./...`, plus `make test` for the race detector, and starts the server to `curl` both routes before opening the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add health check routes to this Echo API. Read go.mod, main.go, router/router.go, handler/routes.go, handler/handler.go, handler/handler_test.go, handler/user_test.go, db/db.go, Makefile, Dockerfile and .github/workflows/go.yml first. Add GET /healthz that returns 200 with a JSON status, and GET /readyz that pings the database through the *sql.DB gorm exposes with a short timeout and returns 503 with the failing check named when the ping fails. Put them in a new health package with a constructor that takes the *sql.DB, and register them on the root echo instance in main.go, not under the /api group, so they need no token and stay out of the swagger docs. Skip both paths in the request logger. Add a HEALTHCHECK to the Dockerfile that calls /readyz. Write a test for the ready route that passes with an open database and fails after it is closed. Run go build -v ./..., go test -v ./... and make test, start the server and curl both routes, then open a pull request that shows the curl output.",
  "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

What comes back is a pull request that adds `health/health.go` and `health/health_test.go`, changes `main.go` to construct the health handler from `d.DB()` and register the two routes, changes `router/router.go` to skip them in the logger, and adds one `HEALTHCHECK` line to the `Dockerfile`. The description shows the `curl -i` output for `/healthz` and `/readyz` against a running server, the `go test` lines for the new package, and names the two second ping timeout so a reviewer can change it in one place.

The run's record keeps every command: the build, the test runs with and without `-race`, the server start and the two curls, so the proof that the routes answer is in the log and not only in the description.

Before merging, a reviewer decides whether readiness should also check anything beyond the database, whether the Kubernetes or compose probes should point at `/readyz` or `/healthz`, and whether to take the agent's note about the loopback bind address as a follow-up. The agent changes no existing route and no model.

## Run it on every Go service without probes

A team with several Echo services starts one run per repository from its own server: one `POST /o/{org}/sessions` each, 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 instead of opening a second pull request. Each run reads its own `main.go` and finds where the database handle lives in that service.

To keep the probes meaningful after that, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds a datastore or an outbound client the service cannot work without, add it to the readiness check in the health package and say so in a comment" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

A health route written without running the service is wrong in small ways that only show in production: registered under the JWT group so the probe gets `401`, logged on every tick until the access log is useless, or answering `200` while the database is gone. The agent runs the server in its own sandbox, hits both routes, closes the database in a test and watches the answer change, so the pull request carries behaviour and not intent.

Every command stays with the run, from `go build` to the `curl` lines, and the pull request cites them. Doing the same for a dozen Go services at once costs no more attention than one, because each run has its own machine, its own record and its own pull request.

## Frequently asked questions

### Why two routes instead of one?

Because an orchestrator treats them differently. A failing liveness probe restarts the process, which does nothing for a database that is down and would restart a healthy server in a loop. A failing readiness probe only takes the instance out of rotation until the dependency is back. `/healthz` checks the process; `/readyz` checks what the process needs.

### Why ping through gorm's `DB()` rather than run a query?

`jinzhu/gorm` v1.9.8 wraps a `database/sql` pool and exposes it with `d.DB()`, and `PingContext` on that pool is the cheapest honest check: it takes a connection and verifies it. A `SELECT 1` would also work; the ping needs no table and respects the two second context, so a stuck database cannot stall the probe.

### Why do the probes not appear in the Swagger docs?

The `docs/` package is generated by `swag` from annotations on the handlers under `/api`, and the probes are registered on the root instance with no annotations. They are infrastructure, not API, and keeping them out of `swagger.json` means the agent does not regenerate `docs/docs.go` in this pull request. A reviewer who wants them documented can add the annotations and run `swag init`.

### Does the HEALTHCHECK work with the server bound to 127.0.0.1?

Yes, because the check runs inside the container, where `127.0.0.1:8585` is the server's own address. The same bind address means `docker run -p 8585:8585` forwards to nothing from the host; the agent says so in the pull request and leaves the bind address alone, since changing it is a separate decision.

## More Echo jobs

- [Run an Echo App as a Non-Root User in Docker](https://getrush.ai/run/add-non-root-user/echo/)
- [Add OpenTelemetry Tracing to an Echo API](https://getrush.ai/run/add-opentelemetry/echo/)
- [Add Prometheus Metrics to an Echo API](https://getrush.ai/run/add-prometheus-metrics/echo/)

## The same job on other stacks

- [Add Health Checks to an Express API](https://getrush.ai/run/add-health-checks/express/)
- [Add Health Check Endpoints to a FastAPI App](https://getrush.ai/run/add-health-checks/fastapi/)
- [Add Health Checks to a Fastify App](https://getrush.ai/run/add-health-checks/fastify/)

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