health

Documentation

Overview

Package health implements helpers around HTTP endpoints for server health.

Index

• Constants
• func NewLivenessHandlerFunc(opts ...Option) http.HandlerFunc
• func NewReadinessHandlerFunc(opts ...Option) http.HandlerFunc
• type CPUMetrics
• type CheckResults
  • func (checks CheckResults) Status() Status
• type CheckerFunc
• type LivenessResponse
• type MemoryMetrics
• type Option
  • func WithCheck(name string, check CheckerFunc) Option
  • func WithEnvironment(environment string) Option
  • func WithVersion(version string) Option
• type ReadinessResponse
• type RuntimeMetrics
• type Status
  • func (s Status) HTTPCode() int
  • func (s Status) IsHealthy() bool
  • func (s Status) IsReady() bool
  • func (s Status) MarshalText() ([]byte, error)
  • func (s Status) String() string
• type StatusCheck

Constants

const (
	// HTTPLivenessCheckPath is the path where the liveness check handler is accessible.
	HTTPLivenessCheckPath = "/healthz"
	// HTTPReadinessCheckPath is the path where the readiness check handler is accessible.
	HTTPReadinessCheckPath = "/readyz"
)

Functions

func NewLivenessHandlerFunc

func NewLivenessHandlerFunc(opts ...Option) http.HandlerFunc

NewLivenessHandlerFunc returns the liveness checker http.HandlerFunc.

func NewReadinessHandlerFunc

func NewReadinessHandlerFunc(opts ...Option) http.HandlerFunc

NewReadinessHandlerFunc returns the readiness checker http.HandlerFunc.

Types

type CPUMetrics

type CPUMetrics struct {
	Goroutines int `json:"goroutines"` // Goroutines represents the current count of Goroutines.
}

CPUMetrics represents the CPU metrics.

type CheckResults

type CheckResults map[string]StatusCheck

CheckResults represents status checks results.

func (CheckResults) Status

func (checks CheckResults) Status() Status

Status returns outcome status of checks.

type CheckerFunc

type CheckerFunc func() StatusCheck

CheckerFunc represents a function that returns a single status check.

type LivenessResponse

type LivenessResponse struct {
	Timestamp   time.Time              `json:"timestamp"`   // Timestamp represents the timestamp of the response.
	Started     bool                   `json:"started"`     // Started represents whether the application started.
	Status      Status                 `json:"status"`      // Status represents the liveness status.
	Version     string                 `json:"version"`     // Version represents the application version.
	Environment string                 `json:"environment"` // Environment represents the application environment.
	Checks      map[string]StatusCheck `json:"checks"`      // Checks represents the liveness checks.
}

LivenessResponse represents the response of [LivenessHandlerFunc].

type MemoryMetrics

type MemoryMetrics struct {
	UsedBytes    uint64 `json:"used_bytes"`    // UsedBytes represents the current count of memory bytes used.
	MaxBytes     uint64 `json:"max_bytes"`     // MaxBytes represents the maximum count of memory bytes used.
	UsagePercent uint64 `json:"usage_percent"` // UsagePercent represents current percentage of available memory being used.
	GCRuns       uint32 `json:"gc_runs"`       // GCRuns represents the count of garbage collector runs.
}

MemoryMetrics represents the memory metrics.

type Option

type Option func(*config)

Option configures a [Handler].

func WithCheck

func WithCheck(name string, check CheckerFunc) Option

WithCheck registers a named check.

func WithEnvironment

func WithEnvironment(environment string) Option

WithEnvironment sets the application environment for the response.

func WithVersion

func WithVersion(version string) Option

WithVersion sets the application version for the response.

type ReadinessResponse

type ReadinessResponse struct {
	Timestamp      time.Time              `json:"timestamp"`       // Timestamp represents the timestamp of the response.
	Status         Status                 `json:"status"`          // Status represents the readiness status.
	Version        string                 `json:"version"`         // Version represents the application version.
	Environment    string                 `json:"environment"`     // Environment represents the application environment.
	RuntimeMetrics RuntimeMetrics         `json:"runtime_metrics"` // RuntimeMetrics represents the runtime metrics.
	Checks         map[string]StatusCheck `json:"checks"`          // Checks represents the readiness checks.
}

ReadinessResponse represents the response of [ReadinessHandlerFunc].

type RuntimeMetrics

type RuntimeMetrics struct {
	Memory MemoryMetrics `json:"memory"` // Memory represents the memory metrics.
	CPU    CPUMetrics    `json:"cpu"`    // CPU represents the cPU metrics.
}

RuntimeMetrics represents the runtime metrics.

type Status

type Status int

Status represents the health status of a service or component.

const (
	// StatusOK represents the [Status] that means that the app is running fine.
	StatusOK Status = iota
	// StatusDegraded represents the [Status] that means that the app is running, yet has some minor, non-critical, issues.
	StatusDegraded
	// StatusDown represents the [Status] that means that the app in unable to process requests.
	StatusDown
	// StatusUnknown represents the [Status] that means that it is impossible to determine the status of the application.
	StatusUnknown
)

func (Status) HTTPCode

func (s Status) HTTPCode() int

HTTPCode returns the appropriate HTTP status code for s.

func (Status) IsHealthy

func (s Status) IsHealthy() bool

IsHealthy returns whether s is considered healthy Please note that StatusDegraded is still considered as healthy.

func (Status) IsReady

func (s Status) IsReady() bool

IsReady returns whether s is considered ready Please note that StatusDegraded is still considered as ready.

func (Status) MarshalText

func (s Status) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Status) String

func (s Status) String() string

String returns the string representation of s.

type StatusCheck

type StatusCheck struct {
	Status  Status // Status is the check outcome status
	Message string // Message is the message associated with the check
}

StatusCheck represents a Status check.