health

README

health

Health package simplifies the way you add health check to your service.

For a real application using go-health please check ImgArt

Supported Features

• Service health status
• Graceful Shutdown Pattern
• Health check external dependencies
• HTTP Handler out of the box that returns the health status

Installation

go get -u github.com/Talento90/go-health

How to use

    // Create a new instance of Health
    h := New("service-name", Options{checkersTimeout: time.Second * 1})

    // Register external dependencies
    h.RegisterChecker("redis", redisDb)
    h.RegisterChecker("mongo", mongoDb)
    h.RegisterChecker("external_api", api)

    // Get service health status
    s := h.GetStatus()

    // Listen interrupt OS signals for graceful shutdown
    var gracefulShutdown = make(chan os.Signal)

    signal.Notify(gracefulShutdown, syscall.SIGTERM)
    signal.Notify(gracefulShutdown, syscall.SIGINT)

    go func() {
    <-gracefulShutdown
        health.Shutdown()

        // Close Databases gracefully
        // Close HttpServer gracefully
    }


    // if you have an http server you can register the default handler
    // ServeHTTP return 503 (Service Unavailable) if service is shutting down
    http.HandleFunc("/health", h.ServeHTTP)

Response Example

{  
    "service":"imgart",
    "up_time":"14m5.788341028s",
    "start_time":"2018-03-11T17:02:33Z",
    "memory":{
        "current":{
            "total_alloc":8359984,
            "heap_alloc":2285896,
            "rss":5767168
        },
        "initial":{
            "total_alloc":7784792,
            "heap_alloc":1754064,
            "rss":5701632
        },
        "diff":{
            "total_alloc":575192,
            "heap_alloc":531832,
            "rss":65536
        }
    },
    "go_routines":21,
    "is_shutting_down":false,
    "health_checkers":{
        "mongo":{
            "status":"CHECKED",
            "response_time":"573.813µs"
        },
        "redis":{
            "status":"CHECKED",
            "error":{
                "Syscall":"getsockopt",
                "Err":113
            },
            "response_time":"93.526014ms"
        },
        "external_api": {
            "status":"TIMEOUT",
            "response_time":"1.2s"
        }
    }
}

Documentation

Index

• type Checker
• type CheckerResult
• type DiffMemoryStatus
• type Health
  • func New(name string, opt Options) Health
• type Memory
• type MemoryStatus
• type Options
• type Status

Types

type Checker

type Checker interface {
	// Check service health
	Check() error
}

Checker interface checks the health of external services (database, external service)

type CheckerResult

type CheckerResult struct {

	// Status (CHECKED/TIMEOUT)
	Status string `json:"status"`
	// Error
	Error error `json:"error,omitempty"`
	// ResponseTime
	ResponseTime string `json:"response_time"`
	// contains filtered or unexported fields
}

CheckerResult struct represent the result of a checker

type DiffMemoryStatus

type DiffMemoryStatus struct {
	// TotalAlloc is cumulative bytes allocated for heap objects.
	TotalAlloc int64 `json:"total_alloc"`
	// HeapAlloc is bytes of allocated heap objects.
	HeapAlloc int64 `json:"heap_alloc"`
	// ResidentSetSize is bytes of heap memory obtained from the OS.
	ResidentSetSize int64 `json:"rss"`
}

DiffMemoryStatus contains memory statistics

type Health

type Health interface {
	// GetStatus return the current status of the service
	GetStatus() *Status
	// RegisterChecker register a service to check their health
	RegisterChecker(name string, check Checker)
	// ServeHTTP handler for http services
	ServeHTTP(w http.ResponseWriter, r *http.Request)
	// Shutdown set isShutdown flag meaning the service is shutting down
	Shutdown()
}

Health interface

func New

func New(name string, opt Options) Health

New returns a new Health

type Memory

type Memory struct {
	// Current statistics
	Current MemoryStatus `json:"current"`
	// Inital statistics when Health was created
	Initial MemoryStatus `json:"initial"`
	// Diff statistics between Current - Initial
	Diff DiffMemoryStatus `json:"diff"`
}

Memory contains the current, initial and difference statistics

type MemoryStatus

type MemoryStatus struct {
	// TotalAlloc is cumulative bytes allocated for heap objects.
	TotalAlloc uint64 `json:"total_alloc"`
	// HeapAlloc is bytes of allocated heap objects.
	HeapAlloc uint64 `json:"heap_alloc"`
	// ResidentSetSize is bytes of heap memory obtained from the OS.
	ResidentSetSize uint64 `json:"rss"`
}

MemoryStatus contains memory statistics

type Options

type Options struct {
	// CheckersTimeout is the timeout value when checking the health of registed checkers
	CheckersTimeout time.Duration
}

Options of Health instance

type Status

type Status struct {
	// Service name
	Service string `json:"service"`
	// Uptime of the service (How long service is running)
	Uptime string `json:"up_time"`
	// StartTime
	StartTime string `json:"start_time"`
	// Memory statistics
	Memory Memory `json:"memory"`
	// GoRoutines being used
	GoRoutines int `json:"go_routines"`
	// IsShuttingDown is active
	IsShuttingDown bool `json:"is_shutting_down"`
	// HealthCheckers status
	HealthCheckers map[string]CheckerResult `json:"health_checkers"`
}

Status of the service