health

Documentation

Overview

Package health implements a component that monitors the health of other components.

The health component supports monitoring several kinds of components. "Simple" components record their health status with this component with simple function calls. If such a component deadlocks, the health component will be unaware.

Actor-based components can register and receive a channel from which they must read within a configured amount of time. This approach makes sense for components using the [actor model](https://en.wikipedia.org/wiki/Actor_model), where the component is considered unhealthy if it is not polling for events frequently.

The health component is ready for registration as soon as it is initialized, and registration must be completed before the health component starts.

All of the component's methods can be called concurrently.

Index

• Variables
• type ActorRegistration
  • func (reg *ActorRegistration) Chan() <-chan struct{}
  • func (reg *ActorRegistration) Stop()
• type Component
• type ComponentHealth
• type SimpleRegistration
  • func (reg *SimpleRegistration) SetHealthy()
  • func (reg *SimpleRegistration) SetUnhealthy(message string)

Variables

var Module = fx.Module(
	"comp/health",
	fx.Provide(newHealth),
)

Module defines the fx options for this component.

Types

type ActorRegistration

type ActorRegistration struct {
	SimpleRegistration
	// contains filtered or unexported fields
}

ActorRegistration is the result of registering with RegisterActor.

func (*ActorRegistration) Chan

func (reg *ActorRegistration) Chan() <-chan struct{}

Chan returns a channel from which the actor must read within the configured duration, or be considered unhealthy. This is the same channel on every call.

func (*ActorRegistration) Stop

func (reg *ActorRegistration) Stop()

Stop permanently stops monitoring of this component. Call this method when the monitored component stops, to avoid spurious check failures. This function must only be called once.

type Component

type Component interface {
	// RegisterSimple registers a component for "simple" monitoring.  It is assumed
	// to be healthy initially, and that status can be updated with methods on the
	// returned value.
	//
	// Component is the component's package path (e.g., `comp/health`).
	RegisterSimple(component string) *SimpleRegistration

	// RegisterActor register a component for "actor" monitoring.  Once the app
	// starts, the actor must read from the channel in the returned value
	// within the given duration, or it will be considered unhealthy.
	//
	// To use: call `RegisterActor` in the component constructor, and store the
	// resulting registration.  At the beginning of the actor's run function,
	// defer a call to reg.Stop().  Within the actor's run loop, read from
	// reg.Chan().
	//
	// Component is the component's package path (e.g., `comp/health`).
	RegisterActor(component string, healthDuration time.Duration) *ActorRegistration

	// GetHealth gets a map containing the health of all components.  This map is a copy
	// and will not be altered after return.
	GetHealth() map[string]ComponentHealth
}

Component is the component type.

type ComponentHealth

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

type SimpleRegistration

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

SimpleRegistration is the result of registering with RegisterSimple.

func (*SimpleRegistration) SetHealthy

func (reg *SimpleRegistration) SetHealthy()

SetHealthy records this component as being healthy. This can be called at any time.

func (*SimpleRegistration) SetUnhealthy

func (reg *SimpleRegistration) SetUnhealthy(message string)

SetUnhealthy records this component as being unhealthy, with the included message summarizing the problem. This can be called at any time.