All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading