healthz

README

Healthz

Examples

• healthz.NewHandler()

Features

• Overall Health Calculation using Subcomponents' Severity and Health Levels
• HTML Report
• JSON Report
• Kubernetes Liveness and Readiness
  • Reports the service as live when the overall health is over Error
  • Reports the service as ready when the overall health is at least on Normal

TODO

• gRPC Report

Documentation

Overview

Package healthz is a status reporter library for microservices. It models the system as a hierarchicy subcomponents, and calculate the overall health usng the overall health of the direct subcomponets of the root component. The handler exposes the health reports in multiple formats:

• HTML Report (`/`)
• JSON Report (`/json`)
• Liveness (`/liveness`): HTTP 200 only if the overall health is > `Error`
• Readiness (`/readiness`): HTTP 200 only if the overall health is >= `Normal`

Check the example, or run the demo:

$GOPATH/src/github.com/cafebazaar/healthz/demo$ go run main.go

Index

• Constants
• type ComponentGroup
• type GroupReport
  • func (rc *GroupReport) Len() int
  • func (rc *GroupReport) Less(i, j int) bool
  • func (rc *GroupReport) Swap(i, j int)
• type Handler
  • func NewHandler(serviceSignature string, details bool) *Handler
  • func (h *Handler) GroupReport() *GroupReport
  • func (h *Handler) OverallHealth() Health
  • func (h *Handler) RegisterSubcomponent(name string, severity Severity) ComponentGroup
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) SetGroupHealth(health Health)
  • func (h *Handler) UnregisterSubcomponent(name string)
• type Health
• type Severity

Examples

• NewHandler

Constants

const (
	// Major means this component's failour disruptes some major
	// functionalities of the system.
	Major Severity = 1

	// Unspecified is the default value of Severity
	Unspecified Severity = 0

	// Minor means this component's failour causes non-critical loss of some
	// functionalities of the system.
	Minor Severity = -1

	// Redundant means there are multiple instances of this components ready to serve
	Redundant Health = 2

	// Normal means there is at least one instance of this component ready to serve
	Normal Health = 1

	// Unknown is the default value of Health
	Unknown Health = 0

	// Warning means there are some problems with this component
	Warning Health = -1

	// Error means that this components is unable to serve as expected
	Error Health = -2
)

Types

type ComponentGroup

type ComponentGroup interface {
	// SetGroupHealth sets the health level of the specified component.
	SetGroupHealth(health Health)

	// RegisterSubcomponent creates a subcomponent if it wasn't registered
	// before, and sets the severity level of the subcomponent to the given
	// value.
	RegisterSubcomponent(name string, severity Severity) ComponentGroup

	// UnregisterSubcomponent removes the subcomponent from the group, and the
	// calculation of the `OverallHealth`
	UnregisterSubcomponent(name string)

	// OverallHealth is the specified value set by `SetGroupHealth`, or if the
	// this instance contains one or more subcomponents, it's the minimum value
	// of these two:
	//	* Minimum health level of all the subcomponents with severity=Major
	//	* 1 + Minimum health level of all the components with severity=Unspecified
	// If no Major or Unspecified component is registered, OverallHealth
	// returns Unknown.
	// Otherwise, if no Major component is registered, the result will be
	// capped at Normal
	OverallHealth() Health

	// GroupReport copies the current status of the group and its subcomponents,
	// and returns the copied object
	GroupReport() *GroupReport
}

ComponentGroup represents a component or a group of components. You can set health level of the group by calling `SetGroupHealth`, OR, by creating subcomponents. Note that you can't mix these two mechanism, it will cause panic!

type GroupReport

type GroupReport struct {
	Name          string
	Severity      Severity
	OverallHealth Health
	Subcomponents []*GroupReport `json:",omitempty"`
}

GroupReport is a copied status of a group and its subcomponents

func (*GroupReport) Len

func (rc *GroupReport) Len() int

func (*GroupReport) Less

func (rc *GroupReport) Less(i, j int) bool

func (*GroupReport) Swap

func (rc *GroupReport) Swap(i, j int)

type Handler

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

Handler is a http handler which is notified about health level of the different components in the system, and reports them through http

func NewHandler

func NewHandler(serviceSignature string, details bool) *Handler

NewHandler creates a Handler and returns it. if details is true, these values are also included in the applicable reports:

• Uptime: since call of this function
• Service Signature: which is passed to this function
• Hostname: which is extracted using `os.Hostname()`
• Health level and Severity level for all the registered components

Example

Example code, to be placed in the main of the application

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/cafebazaar/healthz"
)

type testComponent struct {
	h healthz.ComponentGroup
}

func NewImportantComponent(args string, h healthz.ComponentGroup) *testComponent {
	h.SetGroupHealth(healthz.Warning)
	return &testComponent{h: h}
}

func (c *testComponent) Fix() {
	c.h.SetGroupHealth(healthz.Redundant)
}

// Example code, to be placed in the main of the application
func main() {
	healthzHandler := healthz.NewHandler("Application V1.0.0", true)
	mainHealth := healthzHandler.RegisterSubcomponent("main", healthz.Major)

	// Start Status Server
	healthzServer := &http.Server{
		Addr:    "127.0.0.1:8090",
		Handler: healthzHandler,
	}
	go func() {
		err := healthzServer.ListenAndServe()
		if err != nil {
			log.Fatalln("Error while healthzServer.ListenAndServe():", err)
		}
	}()

	fmt.Println("Overall Health:", healthzHandler.OverallHealth())

	// Create and pass `ComponentGroup`s to the components
	componentHealth := healthzHandler.RegisterSubcomponent("important-component", healthz.Major)
	component := NewImportantComponent("init-component-in-warning-mode", componentHealth)

	fmt.Println("important-component Health:", componentHealth.OverallHealth())
	fmt.Println("Overall Health:", healthzHandler.OverallHealth())

	component.Fix()
	fmt.Println("important-component Health:", componentHealth.OverallHealth())
	fmt.Println("Overall Health:", healthzHandler.OverallHealth())

	// Mark "main" as ready when all the components are initialized
	mainHealth.SetGroupHealth(healthz.Normal)
	fmt.Println("Overall Health:", healthzHandler.OverallHealth())

}

Output:

Overall Health: 0
important-component Health: -1
Overall Health: -1
important-component Health: 2
Overall Health: 0
Overall Health: 1

func (*Handler) GroupReport

func (h *Handler) GroupReport() *GroupReport

GroupReport copies the current status of the root and its subcomponents, and returns the copied object

func (*Handler) OverallHealth

func (h *Handler) OverallHealth() Health

OverallHealth is the overall health level of the handler. Its calculation is described in the doc of `ComponentGroup.OverallHealth`

func (*Handler) RegisterSubcomponent

func (h *Handler) RegisterSubcomponent(name string, severity Severity) ComponentGroup

RegisterSubcomponent creates a subcomponent if it wasn't registered before, and sets the severity level of the component to the given value

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is implemented to response to the report requests

func (*Handler) SetGroupHealth

func (h *Handler) SetGroupHealth(health Health)

SetGroupHealth sets the health level of the root component. Note that you can't mix SetGroupHealth and RegisterSubcomponent

func (*Handler) UnregisterSubcomponent

func (h *Handler) UnregisterSubcomponent(name string)

UnregisterSubcomponent removes the subcomponent from the group, the reports, and the calculation of the `OverallHealth`

type Health

type Health int8

Health specifies if a component is ready or not

type Severity

type Severity int8

Severity specifies the seriousness of a component