Documentation
¶
Overview ¶
Package healthz provides tools for service health checks
The easiest way to setup Kubernetes-like liveness and readiness checks:
liveness := healthz.NewTCPChecker(":80")
readiness := healthz.NewStatusChecker()
// Exposes "/healthz" for liveness, "/readiness" for readiness checks
handler := healthz.NewHealthServiceHandler(liveness, readiness)
http.ListenAndServe(":8081", handler)
Setup the health service with custom paths:
liveness := healthz.NewTCPChecker(":80")
readiness := healthz.NewStatusChecker()
healthService := NewHealthService(livenessChecker, readinessChecker)
mux := http.NewServeMux()
mux.HandleFunc("/liveness", healthService.HealthStatus)
mux.HandleFunc("/readiness", healthService.ReadinessStatus)
http.ListenAndServe(":8081", mux)
Index ¶
- Variables
- func NewHealthServiceHandler(livenessChecker Checker, readinessChecker Checker) http.Handler
- type AlwaysFailureChecker
- type AlwaysSuccessChecker
- type CheckFunc
- type Checker
- type Checkers
- type HTTPChecker
- type HTTPCheckerOption
- type HealthService
- type PingChecker
- type Pinger
- type Status
- type StatusChecker
- type TCPChecker
- type TCPCheckerOption
Constants ¶
This section is empty.
Variables ¶
var ErrCheckFailed = errors.New("Check failed")
ErrCheckFailed is a generic error which MAY be returned when a check fails.
Functions ¶
Types ¶
type AlwaysFailureChecker ¶ added in v0.4.0
type AlwaysFailureChecker struct{}
AlwaysFailureChecker always returns failure as the check result.
This is useful for testing purposes.
func (*AlwaysFailureChecker) Check ¶ added in v0.4.0
func (c *AlwaysFailureChecker) Check() error
Check implements the Checker interface.
type AlwaysSuccessChecker ¶ added in v0.4.0
type AlwaysSuccessChecker struct{}
AlwaysSuccessChecker always returns success as the check result.
This is useful for testing purposes.
func (*AlwaysSuccessChecker) Check ¶ added in v0.4.0
func (c *AlwaysSuccessChecker) Check() error
Check implements the Checker interface.
type CheckFunc ¶ added in v0.4.0
type CheckFunc func() error
CheckFunc is a convenience type to create functions that implement the Checker interface.
type Checker ¶ added in v0.4.0
type Checker interface {
// Check returns nil if the check passes.
Check() error
}
Checker is the interface for checking different resources.
type Checkers ¶ added in v0.4.0
type Checkers struct {
// contains filtered or unexported fields
}
Checkers is a Checker collection responsible for executing a series of checks and decide if the resource is up or not.
func NewCheckers ¶ added in v0.4.0
NewCheckers is a shortcut for easily creating a new Checker collection.
type HTTPChecker ¶ added in v0.4.0
type HTTPChecker struct {
// contains filtered or unexported fields
}
HTTPChecker checks if an HTTP endpoint is available and successfully responds.
func NewHTTPChecker ¶ added in v0.4.0
func NewHTTPChecker(url string, opts ...HTTPCheckerOption) *HTTPChecker
NewHTTPChecker creates a new HTTPChecker with a URL and optional configuration.
Example:
checker := healthz.NewHTTPChecker("http://example.com", healthz.WithHTTPTimeout(3*time.Second))
func (*HTTPChecker) Check ¶ added in v0.4.0
func (c *HTTPChecker) Check() error
Check implements the Checker interface and checks the HTTP endpoint status.
type HTTPCheckerOption ¶ added in v0.6.0
type HTTPCheckerOption func(*HTTPChecker)
HTTPCheckerOption configures how we check the HTTP endpoint.
func WithHTTPMethod ¶ added in v0.6.0
func WithHTTPMethod(method string) HTTPCheckerOption
WithHTTPMethod returns an HTTPCheckerOption that specifies the method for HTTP requests.
The default method is "GET" which works in most of the cases, but another popular choice is "HEAD".
func WithHTTPTimeout ¶ added in v0.6.0
func WithHTTPTimeout(timeout time.Duration) HTTPCheckerOption
WithHTTPTimeout returns an HTTPCheckerOption that specifies the timeout for HTTP requests.
Setting a timeout is highly recommended, but it needs to be carefully chosen to avoid false results.
type HealthService ¶
type HealthService struct {
// contains filtered or unexported fields
}
HealthService is a helper struct which wraps two Checkers and exposes them as HTTP handlers.
func NewHealthService ¶
func NewHealthService(livenessChecker Checker, readinessChecker Checker) *HealthService
NewHealthService creates a new HealthService from user configured Checkers.
func (*HealthService) HealthStatus ¶
func (s *HealthService) HealthStatus(w http.ResponseWriter, r *http.Request)
HealthStatus checks if the application is healthy.
This is identical to liveness checks in Kubernetes. These checks are usually responsible for checking if the app is running (eg. listens on a specific port).
func (*HealthService) ReadinessStatus ¶
func (s *HealthService) ReadinessStatus(w http.ResponseWriter, r *http.Request)
ReadinessStatus checks if the app is ready for accepting request.
This is identical to readiness checks in Kubernetes. These checks are usually responsible for checking if the app is functional (eg. database is available).
type PingChecker ¶ added in v0.5.0
type PingChecker struct {
// contains filtered or unexported fields
}
PingChecker checks if a Pinger responds without an error.
func NewPingChecker ¶ added in v0.5.0
func NewPingChecker(pinger Pinger) *PingChecker
NewPingChecker creates a new PingChecker with a Pinger.
func (*PingChecker) Check ¶ added in v0.5.0
func (c *PingChecker) Check() error
Check implements the Checker interface and checks a resource status by pinging it.
type Pinger ¶ added in v0.5.0
type Pinger interface {
Ping() error
}
Pinger is a commonly used interface to check if a connection is alive (used in sql.DB for example).
type StatusChecker ¶ added in v0.4.0
type StatusChecker struct {
// contains filtered or unexported fields
}
StatusChecker checks the status based on an internal state.
func NewStatusChecker ¶ added in v0.4.0
func NewStatusChecker(status Status) *StatusChecker
NewStatusChecker creates a new StatusChecker with an initial state.
func (*StatusChecker) Check ¶ added in v0.4.0
func (c *StatusChecker) Check() error
Check implements the Checker interface and checks the internal state. Returns an error if the value of state is false.
func (*StatusChecker) SetStatus ¶ added in v0.4.0
func (c *StatusChecker) SetStatus(status Status)
SetStatus sets the internal state of the checker.
type TCPChecker ¶ added in v0.6.0
type TCPChecker struct {
// contains filtered or unexported fields
}
TCPChecker checks if something is listening on a TCP address.
func NewTCPChecker ¶ added in v0.6.0
func NewTCPChecker(addr string, opts ...TCPCheckerOption) *TCPChecker
NewTCPChecker creates a new TCPChecker with an address and optional configuration. Example:
checker := healthz.NewTCPChecker(":80", healthz.WithTCPTimeout(3*time.Second))
func (*TCPChecker) Check ¶ added in v0.6.0
func (c *TCPChecker) Check() error
Check implements the Checker interface and checks the TCP address status.
type TCPCheckerOption ¶ added in v0.6.0
type TCPCheckerOption func(*TCPChecker)
TCPCheckerOption configures how we check the TCP address.
func WithTCPTimeout ¶ added in v0.6.0
func WithTCPTimeout(timeout time.Duration) TCPCheckerOption
WithTCPTimeout returns a TCPCheckerOption that specifies the timeout for TCP requests.
Setting a timeout is highly recommended, but it needs to be carefully chosen to avoid false results.