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

🚀 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))
}

Example handler response:

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

🧪 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

• 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 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

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 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"
)