healthcheck

README

healthcheck

Healthcheck for Go services.

Document

pkg.go.dev

Features

• Support background checks.
  • To protect services with expensive checks.
  • To improve response time of health check request.
• Support threshold for number of errors in a row.
• A Detailed format.
  • By default, response do not have body.
  • Pass detail query parameter in the request for detailed response. Good for debugging.

Motivation

Other implementations, has one of these 2 issues:

• Don't support background checks.
• Run a go routine per background check.

Usage

Running Service

• Create a new ServeMux. Or use http.DefaultServeMux.

serveMux := http.NewServeMux()

• Create a new HealthCheck instance. Pass ServeMux and healthcheck path.

h := healthcheck.New(serveMux, "/healthcheck")

• Register as many as checks you have.
  • name: A unique name per check.
  • check: Check function.
  • timeout: Timeout of check.
  • opts: Check options. Type CheckOption. Checker Options section

h.Register("check 1", checkOne, time.Second)
h.Register("check 2", checkTwo, time.Second*10, InBackground(time.Minute*10))

• Run it (If you don't have background checks, no need for this step). Remember to close it.

h.Run(context.Background())
defer h.Close()

Creating Checkers

A checker is a function with this signature:

type Checker func(ctx context.Context) error

Healthcheck has built-in timeouts for checks, no need to add it in checker. ctx is with a timeout, use it to release resources if needed.

Checker Options

Pass checker options when registering checks to modify the behavior.

• InBackground forces a check to run in the background.

InBackground(interval time.Duration)

• WithThreshold adds a threshold of errors in the row to show unhealthy state.

WithThreshold(threshold uint)

Examples

For creating new Checks, checkers package has some examples.

Executable example in pkg.go.dev.

License

This project is licensed under the terms of the Mozilla Public License 2.0.

Documentation

Overview

Package healthcheck provides easy to register and manage health checks for services.

Example

ctx := context.Background()
var (
	serviceIsUnhealthy bool
	// If Checker has changing variable, use mutex to handle race condition.
	mutex sync.RWMutex
)
dummyHealthyChecker := func(_ context.Context) error {
	return nil
}
dummyUnhealthyChecker := func(_ context.Context) error {
	mutex.RLock()
	defer mutex.RUnlock()
	if serviceIsUnhealthy {
		return errors.New("not_feeling_good")
	}
	return nil
}

serveMux := http.NewServeMux()

h := New(serveMux, "/healthcheck")
h.Register("dummy_healthy_checker", dummyHealthyChecker, time.Second)
h.Register("dummy_unhealthy_checker_in_background", dummyUnhealthyChecker, time.Second*2, InBackground(time.Millisecond))
h.Register("dummy_unhealthy_checker_with_threshold", dummyUnhealthyChecker, time.Second, WithThreshold(2))
h.Run(ctx)
defer h.Close()

time.Sleep(time.Millisecond * 10)

// check method is not exposed. Don't use it in your codes.
fmt.Println(h.check(ctx))

// Lets make unhealthy checkers fail
mutex.Lock()
serviceIsUnhealthy = true
mutex.Unlock()
time.Sleep(time.Millisecond * 10)

fmt.Println(h.check(ctx))
fmt.Println(h.check(ctx))

Output:

map[]
map[dummy_unhealthy_checker_in_background:not_feeling_good]
map[dummy_unhealthy_checker_in_background:not_feeling_good dummy_unhealthy_checker_with_threshold:not_feeling_good]

Index

• type CheckOption
  • func InBackground(interval time.Duration) CheckOption
  • func WithThreshold(threshold uint) CheckOption
• type Checker
• type HealthCheck
  • func New(serve *http.ServeMux, handlerPattern string) *HealthCheck
  • func (h *HealthCheck) Close()
  • func (h *HealthCheck) Register(name string, c Checker, timeout time.Duration, opts ...CheckOption)
  • func (h *HealthCheck) Run(ctx context.Context)

Examples

• Package

Types

type CheckOption

type CheckOption func(c *check)

A CheckOption is a modifier of a check. It can be passed while registering a checker to customize it.

func InBackground

func InBackground(interval time.Duration) CheckOption

InBackground forces a check to run in the background. Returns a CheckOption that can be passed during the Checker registration.

func WithThreshold

func WithThreshold(threshold uint) CheckOption

WithThreshold adds a threshold of errors in the row to show unhealthy state. Returns a CheckOption that can be passed during the Checker registration.

type Checker

type Checker func(ctx context.Context) error

A Checker is a function responsible to check the status of a service and return an error if service is unhealthy.

type HealthCheck

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

A HealthCheck holds all details of checkers and manage their executions.

func New

func New(serve *http.ServeMux, handlerPattern string) *HealthCheck

New creates a new HealthCheck.

serve			ServeMux to register handler. If not sure, pass http.DefaultServeMux.
handlerPattern	patten for handler (e.g. "/healthcheck").

func (*HealthCheck) Close

func (h *HealthCheck) Close()

Close stops running of the background checkers and release resources.

func (*HealthCheck) Register

func (h *HealthCheck) Register(name string, c Checker, timeout time.Duration, opts ...CheckOption)

Register will register a Checker for a HealthCheck. Params:

name	Name of the check. Will be used in the detailed output.
c 		The check function.
timeout	Timeout of the check execution.
opts	Checker options e.g. run in background.

func (*HealthCheck) Run

func (h *HealthCheck) Run(ctx context.Context)

Run executes a goroutine that runs background checkers.