healthz

README

go-healthz

go get gopkg.in/pantheon-systems/go-healthz.v1

Package that implements a healthz healthcheck server.

Inspired by kelseyhightower:

• https://github.com/kelseyhightower/app-healthz
• https://vimeo.com/173610242

Add a Healthz() function to your application components, and then register them with this package along with a type and description by adding them to config.Providers. This package creates a HTTP server that runs all the registered handlers when hitting /healthz and returns any errors.

This server does not use TLS, as most of our applications already run their own TLS servers. One approach is to not expose this server's port directly (except for exposing the basic handler for Kube's liveness and readiness), and rather call the healthz handler internally from a TLS handler that you add to your main TLS server.

Example usage

Setup and calling

logger = logrus.WithField("component", "healthz")
config = healthz.Config{
    BindPort: 8080,
    BindAddr: "localhost",
    Hostname: "pod1",  // empty string will autodetect
    Providers: []healthz.ProviderInfo{
        {
            Type:        "DBConn",
            Description: "Ensure the database is reachable",
            Check: db, // `db` implements `healthz.HealthCheckable()`
        },
        {
            Type:        "Metric",
            Description: "Watch a key metric for failure",
            Check: service, // `service` implements `healthz.HealthCheckable()`
        },
    },
    Log: logger, // logrus
    ServerErrorLog: stdlog.New(logger.Logger.Writer(), "", 0), // stdlib log helper that sends http.Server errors to logrus.
}
healthServer, err := healthz.New(config)
if err != nil {
    return err
}
go healthServer.StartHealthz()

Sensu

Can be used as a Sensu check with the http plugin, for example:

"command": "/path/to/ruby /path/to/check-http.rb
  -c /path/to/client/cert/cert.pem
  -q '\"Errors\":null'
  -C /path/to/ca.crt
  -u https://my.service.com/healthz"

Sensu alerts when the check either returns non-200 response, or does not contain "Errors": null in the body. This is useful as it communicates the error message and nature of the failure to the person reading the check result.

Documentation

Index

• type Config
• type Error
• type HTTPResponse
• type HealthCheckable
• type HealthChecker
  • func New(config Config) (*HealthChecker, error)
  • func (h *HealthChecker) HandleHealthz(w http.ResponseWriter, r *http.Request)
  • func (h *HealthChecker) HandleLiveness(w http.ResponseWriter, r *http.Request)
  • func (h *HealthChecker) StartHealthz()
• type ProviderInfo

Types

type Config

type Config struct {
	BindPort       int
	BindAddr       string
	Providers      []ProviderInfo
	Hostname       string
	Log            logger
	ServerErrorLog *log.Logger
}

type Error

type Error struct {
	Type        string
	ErrMsg      string
	Description string
}

type HTTPResponse

type HTTPResponse struct {
	Errors   []Error
	Hostname string
}

type HealthCheckable

type HealthCheckable interface {
	HealthZ() error
}

type HealthChecker

type HealthChecker struct {
	Server *http.Server
	// contains filtered or unexported fields
}

func New

func New(config Config) (*HealthChecker, error)

func (*HealthChecker) HandleHealthz

func (h *HealthChecker) HandleHealthz(w http.ResponseWriter, r *http.Request)

HandleHealthz is the http handler for `/healthz`

func (*HealthChecker) HandleLiveness

func (h *HealthChecker) HandleLiveness(w http.ResponseWriter, r *http.Request)

HandleLiveness is the http handler for `/liveness`

func (*HealthChecker) StartHealthz

func (h *HealthChecker) StartHealthz()

StartHealthz should be run in a new goroutine.

type ProviderInfo

type ProviderInfo struct {
	Check       HealthCheckable
	Description string
	Type        string
}