health

README

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

Documentation

Index

• Variables
• func GenerateBootstrapDashboardHTML(title string, response DashboardResponse) (string, error)
• type Checker
• type DBChecker
  • func NewDBChecker(name string, db *sql.DB) *DBChecker
  • func (c *DBChecker) Check(ctx context.Context) Result
  • func (c *DBChecker) Name() string
• type Dashboard
  • func NewDashboard(timeout time.Duration) *Dashboard
  • func (d *Dashboard) BootstrapHandler(title string) gin.HandlerFunc
  • func (d *Dashboard) Handler() gin.HandlerFunc
  • func (d *Dashboard) RegisterWebsite(name, url string, client *http.Client) error
  • func (d *Dashboard) Run(ctx context.Context) DashboardResponse
  • func (d *Dashboard) Websites() []Website
• type DashboardResponse
• type DiskChecker
  • func NewDiskChecker(name string, path string, minFreeBytes uint64) *DiskChecker
  • func (c *DiskChecker) Check(ctx context.Context) Result
  • func (c *DiskChecker) Name() string
• type FuncChecker
  • func NewFuncChecker(name string, fn func(ctx context.Context) Result) *FuncChecker
  • func (c *FuncChecker) Check(ctx context.Context) Result
  • func (c *FuncChecker) Name() string
• type HTTPChecker
  • func NewHTTPChecker(name, url string, client *http.Client) *HTTPChecker
  • func (c *HTTPChecker) Check(ctx context.Context) Result
  • func (c *HTTPChecker) Name() string
• type Health
  • func New(timeout time.Duration) *Health
  • func (h *Health) Handler() gin.HandlerFunc
  • func (h *Health) Register(checker Checker)
  • func (h *Health) RunChecks(ctx context.Context) Response
• type Response
• type Result
• type Status
• type Website
• type WebsiteHealth

Variables

var (
	ErrWebsiteNameRequired      = errors.New("website name is required")
	ErrWebsiteURLRequired       = errors.New("website url is required")
	ErrWebsiteAlreadyRegistered = errors.New("website is already registered")
)

Functions

func GenerateBootstrapDashboardHTML

func GenerateBootstrapDashboardHTML(title string, response DashboardResponse) (string, error)

Types

type Checker

type Checker interface {
	Name() string
	Check(ctx context.Context) Result
}

type DBChecker

type DBChecker struct {
	// contains filtered or unexported fields
}

func NewDBChecker

func NewDBChecker(name string, db *sql.DB) *DBChecker

func (*DBChecker) Check

func (c *DBChecker) Check(ctx context.Context) Result

func (*DBChecker) Name

func (c *DBChecker) Name() string

type Dashboard

type Dashboard struct {
	// contains filtered or unexported fields
}

func NewDashboard

func NewDashboard(timeout time.Duration) *Dashboard

func (*Dashboard) BootstrapHandler

func (d *Dashboard) BootstrapHandler(title string) gin.HandlerFunc

func (*Dashboard) Handler

func (d *Dashboard) Handler() gin.HandlerFunc

func (*Dashboard) RegisterWebsite

func (d *Dashboard) RegisterWebsite(name, url string, client *http.Client) error

func (*Dashboard) Run

func (d *Dashboard) Run(ctx context.Context) DashboardResponse

func (*Dashboard) Websites

func (d *Dashboard) Websites() []Website

type DashboardResponse

type DashboardResponse struct {
	Status   Status                   `json:"status"`
	Websites map[string]WebsiteHealth `json:"websites"`
}

type DiskChecker

type DiskChecker struct {
	// contains filtered or unexported fields
}

func NewDiskChecker

func NewDiskChecker(name string, path string, minFreeBytes uint64) *DiskChecker

func (*DiskChecker) Check

func (c *DiskChecker) Check(ctx context.Context) Result

func (*DiskChecker) Name

func (c *DiskChecker) Name() string

type FuncChecker

type FuncChecker struct {
	// contains filtered or unexported fields
}

func NewFuncChecker

func NewFuncChecker(name string, fn func(ctx context.Context) Result) *FuncChecker

func (*FuncChecker) Check

func (c *FuncChecker) Check(ctx context.Context) Result

func (*FuncChecker) Name

func (c *FuncChecker) Name() string

type HTTPChecker

type HTTPChecker struct {
	// contains filtered or unexported fields
}

func NewHTTPChecker

func NewHTTPChecker(name, url string, client *http.Client) *HTTPChecker

func (*HTTPChecker) Check

func (c *HTTPChecker) Check(ctx context.Context) Result

func (*HTTPChecker) Name

func (c *HTTPChecker) Name() string

type Health

type Health struct {
	// contains filtered or unexported fields
}

func New

func New(timeout time.Duration) *Health

func (*Health) Handler

func (h *Health) Handler() gin.HandlerFunc

func (*Health) Register

func (h *Health) Register(checker Checker)

func (*Health) RunChecks

func (h *Health) RunChecks(ctx context.Context) Response

type Response

type Response struct {
	Status   Status            `json:"status"`
	Services map[string]Result `json:"services"`
}

type Result

type Result struct {
	Status       Status                 `json:"status"`
	Type         string                 `json:"type,omitempty"`
	ResponseTime int64                  `json:"response_time_ms"`
	Error        string                 `json:"error,omitempty"`
	Details      map[string]interface{} `json:"details,omitempty"`
}

type Status

type Status string

const (
	StatusUp       Status = "UP"
	StatusDown     Status = "DOWN"
	StatusDegraded Status = "DEGRADED"
)

type Website

type Website struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

type WebsiteHealth

type WebsiteHealth struct {
	Website Website `json:"website"`
	Result  Result  `json:"result"`
}