health

lightweight health checks for Go services
Register custom checks, verify HTTP endpoints and database connectivity, monitor disk usage, and expose a Gin health endpoint.

Features · Quick start · Testing · Contributing

✨ Features

• Register custom checks with the Checker interface or FuncChecker
• Verify HTTP endpoints with HTTPChecker
• Check database availability with DBChecker
• Monitor free disk space with DiskChecker
• Expose results through a Gin-compatible handler
• Build a website dashboard by registering monitored sites

🚀 Quick start

Install the package in your project:

go get github.com/gouef/health

Example usage:

package main

import (
    "context"
    "database/sql"
    "net/http"
    "time"

    _ "github.com/go-sql-driver/mysql"
    "github.com/gouef/health"
)

func main() {
    h := health.New(3 * time.Second)

    h.Register(health.NewFuncChecker("app", func(ctx context.Context) health.Result {
        return health.Result{Status: health.StatusUp, Type: "custom"}
    }))

    h.Register(health.NewHTTPChecker("api", "https://example.com", &http.Client{}))

    db, err := sql.Open("mysql", "user:pass@tcp(localhost:3306)/dbname")
    if err == nil {
        h.Register(health.NewDBChecker("database", db))
    }

    h.Register(health.NewDiskChecker("disk", "/", 100*1024*1024))
}

Expose it through Gin:

import "github.com/gin-gonic/gin"

func main() {
    r := gin.New()
    r.GET("/health", h.Handler())
    _ = r.Run(":8080")
}

Example handler response:

{
  "status": "UP",
  "services": {
    "app": {"status": "UP", "type": "custom", "response_time_ms": 0},
    "api": {"status": "UP", "type": "http", "response_time_ms": 42}
  }
}

Dashboard usage (master website/server):

dashboard := health.NewDashboard(3 * time.Second)

_ = dashboard.RegisterWebsite("landing", "https://example.com", nil)
_ = dashboard.RegisterWebsite("api", "https://api.example.com/health", nil)

r := gin.New()
r.GET("/dashboard", dashboard.Handler())
r.GET("/dashboard/html", dashboard.BootstrapHandler("Master Dashboard"))

You can also generate HTML manually from a template response:

response := dashboard.Run(context.Background())
html, err := health.GenerateBootstrapDashboardHTML("Master Dashboard", response)
if err != nil {
  panic(err)
}

_ = html

Example dashboard response:

{
  "status": "UP",
  "websites": {
    "landing": {
      "website": {"name": "landing", "url": "https://example.com"},
      "result": {"status": "UP", "type": "http", "response_time_ms": 25}
    }
  }
}

🧪 Testing

Run the test suite:

go test ./...

Generate a coverage report:

go test -covermode=set -coverpkg=./... -coverprofile=coverage.txt . && go tool cover -func=coverage.txt

🤝 Contributing

See CONTRIBUTING.md for development guidelines and contribution steps.

Contributors