health

Documentation

Overview

Package health provides pluggable health checking for an httplb.Client.

This package defines the core types Checker, which creates health check processes for connections. The package also defines the interface Tracker, which is how a health check process communicates results back to a httplb.Client.

The Checker interface is very general and allows health-checking strategies of many shapes, including those that might consult separate ("look aside") data sources for health or even those that use a streaming RPC to have results pushed from a server. This package also includes a default implementation that just does periodic polling using a given Prober. The prober can use the actual connection being checked to send an HTTP request to the address and examine the response.

Index

• Constants
• type Checker
  • func NewPollingChecker(config PollingCheckerConfig, prober Prober) Checker
• type PollingCheckerConfig
• type Prober
  • func NewSimpleProber(path string) Prober
• type State
  • func (s State) String() string
• type Tracker

Constants

const (
	StateHealthy   = State(-1)
	StateUnknown   = State(0)
	StateDegraded  = State(1)
	StateUnhealthy = State(2)
)

Types

type Checker

type Checker interface {
	// New creates a new health-checking process for the given connection.
	// The process should release resources (including stopping any goroutines)
	// when the given context is cancelled or the returned value is closed.
	//
	// The process should use the Tracker to record the results of the
	// health checks. It should NOT directly call Tracker from this
	// method implementation. If the implementation wants to immediately
	// update health state, it must do so from a goroutine.
	New(context.Context, conn.Conn, Tracker) io.Closer
}

Checker manages health checks. It creates new checking processes as new connections are created. Each process can be independently stopped.

var (
	// NopChecker is a checker implementation that does nothing. It assumes
	// the state of all connections is healthy.
	NopChecker Checker = nopChecker{}
)

func NewPollingChecker

func NewPollingChecker(config PollingCheckerConfig, prober Prober) Checker

NewPollingChecker creates a new checker that calls a single-shot prober on a fixed interval.

type PollingCheckerConfig

type PollingCheckerConfig struct {
	// How often the probe is performed. Defaults to 15 seconds if zero.
	PollingInterval time.Duration

	// How much to jitter the period. This should be a value between 0 and 1.
	// Zero means no jitter. One means the jitter could perturb the period up
	// to 100% (so the actual period could be between 0 and twice the configured
	// period).
	Jitter float64

	// The time limit for a probe. If it takes longer than this, the health
	// check is assumed to fail as unhealthy. Defaults to the polling period.
	Timeout time.Duration

	// HealthyThreshold specifies the number of successful health checks needed
	// to promote an unhealthy, degraded or unknown backend to healthy. This is
	// not used for the initial health check, so a connection will be healthy
	// immediately if the first health check passes.
	//
	// Defaults to 1.
	HealthyThreshold int

	// UnhealthyThreshold specifies the number of failed health checks needed to
	// demote a healthy connection to unhealthy, degraded, or unknown. This can
	// reduce flapping: Setting this value to two would prevent a single
	// spurious health-check failure from causing a connection to be marked as
	// unhealthy.
	//
	// Defaults to 1.
	UnhealthyThreshold int
}

PollingCheckerConfig represents the configuration options when calling NewPollingChecker.

type Prober

type Prober interface {
	Probe(ctx context.Context, conn conn.Conn) State
}

A Prober is a type that can perform single-shot healthchecks against a connection.

func NewSimpleProber

func NewSimpleProber(path string) Prober

NewSimpleProber creates a new prober that performs an HTTP GET request to the provided path. If it returns a successful status (status codes from 200-299), the connection is considered healthy. Otherwise, it is considered unhealthy.

type State

type State int

State represents the state of a connection. Their natural ordering is for "better" states to be before "worse" states. So StateHealthy is the lowest value and StateUnhealthy is the highest.

func (State) String

func (s State) String() string

type Tracker

type Tracker interface {
	UpdateHealthState(conn.Conn, State)
}

Tracker represents an object that tracks the health state of various connections. This is the interface through which a Checker communicates state updates.