healthz

Documentation

Overview

Package healthz provides an HTTP handler which returns the health status of one or more components of an application or service.

Index

• Constants
• type AlreadyRegisteredError
  • func (are AlreadyRegisteredError) Error() string
• type FailedCheck
• type HealthChecker
• type HealthHandler
  • func NewHealthHandler() *HealthHandler
  • func (h *HealthHandler) DeregisterChecker(component string)
  • func (h *HealthHandler) RegisterChecker(component string, checker HealthChecker) error
  • func (h *HealthHandler) RunChecks(ctx context.Context) []FailedCheck
  • func (h *HealthHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (h *HealthHandler) SetTimeout(timeout time.Duration)
• type HealthStatus

Constants

const (
	// StatusOK is returned if all health checks pass.
	StatusOK = "OK"
	// StatusUnavailable is returned if any health check fails.
	StatusUnavailable = "Service Unavailable"
)

Types

type AlreadyRegisteredError

type AlreadyRegisteredError string

func (AlreadyRegisteredError) Error

func (are AlreadyRegisteredError) Error() string

type FailedCheck

type FailedCheck struct {
	Component string `json:"component"`
	Reason    string `json:"reason"`
}

FailedCheck represents a failed status check for a component.

type HealthChecker

type HealthChecker interface {
	HealthCheck(context.Context) error
}

HealthChecker defines the interface components must implement in order to register with the Handler in order to be included in the health status. HealthCheck is passed a context with a Done channel which is closed due to a timeout or cancellation.

type HealthHandler

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

HealthHandler is responsible for executing registered health checks. It provides an HTTP handler which returns the health status for all registered components.

func NewHealthHandler

func NewHealthHandler() *HealthHandler

NewHealthHandler returns a new HealthHandler instance.

func (*HealthHandler) DeregisterChecker

func (h *HealthHandler) DeregisterChecker(component string)

DeregisterChecker deregisters a named HealthChecker.

func (*HealthHandler) RegisterChecker

func (h *HealthHandler) RegisterChecker(component string, checker HealthChecker) error

RegisterChecker registers a HealthChecker for a named component and adds it to the list of status checks to run. It returns an error if the component has already been registered.

func (*HealthHandler) RunChecks

func (h *HealthHandler) RunChecks(ctx context.Context) []FailedCheck

RunChecks runs all healthCheckers and returns any failures.

func (*HealthHandler) ServeHTTP

func (h *HealthHandler) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServerHTTP is an HTTP handler (see http.Handler) which can be used as an HTTP endpoint for health checks. If all registered checks pass, it returns an HTTP status `200 OK` with a JSON payload of `{"status": "OK"}`. If all checks do not pass, it returns an HTTP status `503 Service Unavailable` with a JSON payload of `{"status": "Service Unavailable","failed_checks":[...]}.

func (*HealthHandler) SetTimeout

func (h *HealthHandler) SetTimeout(timeout time.Duration)

SetTimeout sets the timeout for handling HTTP requests. If not explicitly set, defaults to 30 seconds.

type HealthStatus

type HealthStatus struct {
	Status       string        `json:"status"`
	Time         time.Time     `json:"time"`
	FailedChecks []FailedCheck `json:"failed_checks,omitempty"`
}

HealthStatus represents the current health status of all registered components.