Health Checks

The health package provides a configurable health checker for monitoring database, Redis, external APIs, and plugin dependencies. Use it for load balancer probes, Kubernetes readiness checks, or uptime monitoring.

Overview

The health checker is available on app.Health. Plugins that implement HasHealthChecks automatically register their checks during boot.

Basic usage

checker := health.New()
checker.DB(database.DB)
if rdb != nil {
    checker.Redis(rdb)
}
result := checker.Run(ctx)

Built-in checks

Custom checks

checker.Add("external-api", func(ctx context.Context) error {
    resp, err := http.Get("https://api.example.com/status")
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode != 200 {
        return fmt.Errorf("unexpected status %d", resp.StatusCode)
    }
    return nil
})

checker.Add("disk-space", func(ctx context.Context) error {
    // check available disk space
    return nil
})

Plugin health checks

Plugins implement HasHealthChecks to automatically register checks. These are wired during boot and added to app.Health.

func (p *StripePlugin) HealthChecks() map[string]health.Check {
    return map[string]health.Check{
        "stripe": func(ctx context.Context) error {
            return p.client.Ping(ctx)
        },
    }
}

func (p *RedisPlugin) HealthChecks() map[string]health.Check {
    return map[string]health.Check{
        "redis": func(ctx context.Context) error {
            return p.client.Ping(ctx).Err()
        },
    }
}

Using with app.Health

The app-level health checker aggregates all plugin checks and your custom checks:

// In start/routes.go
app.Router.Get("/health", func(c *http.Context) error {
    result := app.Health.Run(c.Request.Context())
    code := http.StatusOK
    if result.Status != "ok" {
        code = http.StatusServiceUnavailable
    }
    return c.JSON(code, result)
})

Result format

// All healthy:
{
    "status": "ok",
    "checks": {
        "db": "ok",
        "redis": "ok",
        "stripe": "ok"
    }
}

// Degraded:
{
    "status": "degraded",
    "checks": {
        "db": "ok",
        "redis": "connection refused",
        "stripe": "ok"
    }
}

Response codes

• 200 OK — All checks passed.
• 503 Service Unavailable — One or more checks failed.

Timeout

If the request context has no deadline, Run uses a 5-second timeout to avoid hanging health checks.