healthcheck

README

Healthcheck for go applications

This tools allow you to unlock the kubernetes feature Liveness and Readiness.

Features

• Logger to log failed probes
• Automatic, manual and background checks
• Respond with all healthchecks status in JSON format
• Callback for integrate with metrics or other systems
• Integrated web server

Quickstart

go get -u github.com/kazhuravlev/healthcheck

Check an examples.

package main

import (
	"context"
	"errors"
	"math/rand"
	"time"

	"github.com/kazhuravlev/healthcheck"
)

func main() {
	ctx := context.TODO()

	// 1. Init healthcheck instance. It will store all our checks.
	hc, _ := healthcheck.New()

	// 2. Register checks that will random respond with an error.
	hc.Register(ctx, healthcheck.NewBasic("redis", time.Second, func(ctx context.Context) error {
		if rand.Float64() > 0.5 {
			return errors.New("service is not available")
		}

		return nil
	}))

	// 3. Init and run a webserver for integration with Kubernetes.
	sysServer, _ := healthcheck.NewServer(hc, healthcheck.WithPort(8080))
	_ = sysServer.Run(ctx)

	// 4. Open http://localhost:8080/ready to check the status of your system
	select {}
}

Documentation

Index

• func NewBackground(name string, initialErr error, delay, period, timeout time.Duration, ...) *bgCheck
• func NewBasic(name string, timeout time.Duration, fn CheckFn) *basicCheck
• func NewManual(name string) *manualCheck
• func ReadyHandler(healthcheck IHealthcheck) http.HandlerFunc
• func WithCheckStatusFn(fn func(checkID string, isReady Status)) func(*hcOptions)
• func WithHealthcheck(hc *Healthcheck) func(o *serverOptions)
• func WithLogger(logger *slog.Logger) func(o *serverOptions)
• func WithPort(port int) func(o *serverOptions)
• type Check
• type CheckFn
• type CheckState
• type Healthcheck
  • func New(opts ...func(*hcOptions)) (*Healthcheck, error)
  • func (s *Healthcheck) Register(ctx context.Context, check ICheck)
  • func (s *Healthcheck) RunAllChecks(ctx context.Context) Report
• type ICheck
• type IHealthcheck
• type ILogger
• type Report
• type Server
  • func NewServer(hc IHealthcheck, opts ...func(*serverOptions)) (*Server, error)
  • func (s *Server) Run(ctx context.Context) error
• type Status

Functions

func NewBackground

func NewBackground(name string, initialErr error, delay, period, timeout time.Duration, fn CheckFn) *bgCheck

NewBackground will create a check that runs in background. Usually used for slow or expensive checks. Note: period should be greater than timeout.

hc, _ := healthcheck.New(...)
hc.Register(healthcheck.NewBackground("some_subsystem"))

func NewBasic

func NewBasic(name string, timeout time.Duration, fn CheckFn) *basicCheck

NewBasic creates a basic check. This check will only be performed when RunAllChecks is called.

hc, _ := healthcheck.New(...)
hc.Register(healthcheck.NewBasic("postgres", time.Second, func(context.Context) error { ... }))

func NewManual

func NewManual(name string) *manualCheck

NewManual create new check, that can be managed by client. Marked as failed by default.

hc, _ := healthcheck.New(...)
check := healthcheck.NewManual("some_subsystem")
check.SetError(nil)
hc.Register(check)
check.SetError(errors.New("service unavailable"))

func ReadyHandler

func ReadyHandler(healthcheck IHealthcheck) http.HandlerFunc

ReadyHandler build a http.HandlerFunc from healthcheck.

func WithCheckStatusFn

func WithCheckStatusFn(fn func(checkID string, isReady Status)) func(*hcOptions)

WithCheckStatusFn will provide a function that will be called at each check changes.

func WithHealthcheck

func WithHealthcheck(hc *Healthcheck) func(o *serverOptions)

func WithLogger

func WithLogger(logger *slog.Logger) func(o *serverOptions)

func WithPort

func WithPort(port int) func(o *serverOptions)

Types

type Check

type Check struct {
	Name     string       `json:"name"`
	State    CheckState   `json:"state"`
	Previous []CheckState `json:"previous"`
}

type CheckFn

type CheckFn func(ctx context.Context) error

type CheckState

type CheckState struct {
	ActualAt time.Time `json:"actual_at"`
	Status   Status    `json:"status"`
	Error    string    `json:"error"`
}

type Healthcheck

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

func New

func New(opts ...func(*hcOptions)) (*Healthcheck, error)

func (*Healthcheck) Register

func (s *Healthcheck) Register(ctx context.Context, check ICheck)

Register will register a check.

All checks should have a name. Will be better that name will contain only lowercase symbols and lodash. This is allowing to have the same name for Check and for metrics.

func (*Healthcheck) RunAllChecks

func (s *Healthcheck) RunAllChecks(ctx context.Context) Report

RunAllChecks will run all check immediately.

type ICheck

type ICheck interface {
	// contains filtered or unexported methods
}

type IHealthcheck

type IHealthcheck interface {
	RunAllChecks(ctx context.Context) Report
}

type ILogger

type ILogger interface {
	WarnContext(ctx context.Context, msg string, attrs ...any)
	ErrorContext(ctx context.Context, msg string, attrs ...any)
}

type Report

type Report struct {
	Status Status  `json:"status"`
	Checks []Check `json:"checks"`
}

type Server

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

func NewServer

func NewServer(hc IHealthcheck, opts ...func(*serverOptions)) (*Server, error)

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

type Status

type Status string

const (
	StatusUp   Status = "up"
	StatusDown Status = "down"
)