health

README

package health

The health package handles internal healthchecks for the agents, that allow to check every asynchronous component is running as intended.

For more information on the context, see the agent-healthcheck.md proposal.

How to add a component?

• First, you need to register, by calling health.Register with a user-visible name. You will receive a *health.Handle to keep. As soon as Register is called, you need to start reading the channel to be considered healthy.

• If you want to register a component for the Startup probe, you need to call RegisterStartup(). This is useful for components that need to perform some initialization before being considered healthy. You will need to first register the component, then do the initialization, and finally read from the channel.

• In your main goroutine, you need to read from the handle.C channel, at least every 15 seconds. This is accomplished by using a select statement in your main goroutine. If the channel is full (after two tries), your component will be considered unhealthy, which might result in the agent getting killed by the system.

• If your component is stopping, it should call handle.Deregister() before stopping. It will then be removed from the healthcheck system.

Where should I tick?

It depends on your component lifecycle, but the check's purpose is to check that your component is able to process new input and act accordingly. For components that read input from a channel, you should read the channel from this logic.

This is usually highly unlikely, but it's exactly the scope of this system: be able to detect if a component is frozen because of a bug / race condition. This is usually the only kind of issue that could be solved by the agent restarting.

Documentation

Overview

Package health implements the internal healthcheck

Index

• func Deregister(handle *Handle) error
• type Handle
  • func RegisterLiveness(name string) *Handle
  • func RegisterReadiness(name string) *Handle
  • func RegisterStartup(name string) *Handle
  • func (h *Handle) Deregister() error
• type Status
  • func GetLive() Status
  • func GetLiveNonBlocking() (Status, error)
  • func GetReady() (ret Status)
  • func GetReadyNonBlocking() (Status, error)
  • func GetStartup() Status
  • func GetStartupNonBlocking() (Status, error)

Functions

func Deregister

func Deregister(handle *Handle) error

Deregister a component from the healthcheck

Types

type Handle

type Handle struct {
	C <-chan time.Time
}

Handle holds the token and the channel for components to use

func RegisterLiveness

func RegisterLiveness(name string) *Handle

RegisterLiveness registers a component for liveness check with the default 30 seconds timeout, returns a token

func RegisterReadiness

func RegisterReadiness(name string) *Handle

RegisterReadiness registers a component for readiness check with the default 30 seconds timeout, returns a token

func RegisterStartup

func RegisterStartup(name string) *Handle

RegisterStartup registers a component for startup check, returns a token

func (*Handle) Deregister

func (h *Handle) Deregister() error

Deregister allows a component to easily deregister itself

type Status

type Status struct {
	Healthy   []string
	Unhealthy []string
}

Status represents the current status of registered components it is built and returned by GetStatus()

func GetLive

func GetLive() Status

GetLive returns health of all components registered for liveness

func GetLiveNonBlocking

func GetLiveNonBlocking() (Status, error)

GetLiveNonBlocking returns the health of all components registered for liveness with a 500ms timeout

func GetReady

func GetReady() (ret Status)

GetReady returns health of all components registered for both readiness and liveness

func GetReadyNonBlocking

func GetReadyNonBlocking() (Status, error)

GetReadyNonBlocking returns the health of all components registered for both readiness and liveness with a 500ms timeout

func GetStartup

func GetStartup() Status

GetStartup returns health of all components registered for startup

func GetStartupNonBlocking

func GetStartupNonBlocking() (Status, error)

GetStartupNonBlocking returns the health of all components registered for startup with a 500ms timeout