healthcheck

README

Low-dependency, High-efficiency, Kubernetes-style healthcheck for Gin Framework

This module will create a kubernetes-style endpoints for Gin framework. Inspired by tavsec/gin-healthcheck.

📜 Language

English | 简体中文

✨ Core Features

• ⚡ Lightweight
• 🌲 Low dependency (only gin)
• 🔥 High efficiency
• 🔨 Highly customizable
• ⎈ Kubernetes-style

⚙️ Usage

go get github.com/elliotxx/healthcheck

📖 Examples

Default Check

package main

import (
	"github.com/elliotxx/healthcheck"
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	healthcheck.Register(&r.RouterGroup)

	r.Run()
}

This will register the default healthcheck endpoint (/healthz) to the route. The path can be customized using healthcheck.Config structure.

Or use NewHandler() function directly:

package main

import (
	"github.com/elliotxx/healthcheck"
	"github.com/elliotxx/healthcheck/checks"
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET("livez", healthcheck.NewHandler(healthcheck.NewDefaultHandlerConfig()))

	readyzChecks := []checks.Check{checks.NewPingCheck(), checks.NewEnvCheck("DB_HOST")}
	r.GET("readyz", healthcheck.NewHandler(healthcheck.NewDefaultHandlerConfigFor(readyzChecks...)))

	r.Run()
}

Output:

$ curl -k http://localhost:8080/readyz
OK

$ curl -k http://localhost:8080/readyz?verbose
[+] Ping ok
[-] Env-DB_HOST ok
health check failed

$ curl -k http://localhost:8080/readyz?verbose&excludes=Env-DB_HOST
[+] Ping ok
health check passed

Enjoy it!

More examples can be seen: ./example_test.go

Documentation

Overview

Example (CustomHandler)

// Example code
r := gin.Default()

r.GET("livez", NewHandler(NewDefaultHandlerConfig()))
readyzChecks := []checks.Check{checks.NewPingCheck(), checks.NewEnvCheck("DB_HOST")}
r.GET("readyz", NewHandler(NewDefaultHandlerConfigFor(readyzChecks...)))

// Simulate request
dummyRequest(r, "/livez")
dummyRequest(r, "/readyz?verbose")
dummyRequest(r, "/readyz?verbose&excludes=Env-DB_HOST")

Output:

200
OK

503
[+] Ping ok
[-] Env-DB_HOST fail
health check failed

200
[+] Ping ok
health check passed

Example (Register)

// Example code
r := gin.Default()
_ = Register(&r.RouterGroup)

// Simulate request
dummyRequest(r, "/healthz")

Output:

200
OK

Example (RegisterFor)

// Example code
r := gin.Default()

config := NewDefaultConfig()
config.Verbose = true
_ = RegisterFor(&r.RouterGroup, config)

// Simulate request
dummyRequest(r, "/healthz")

Output:

200
[+] Ping ok
health check passed

Index

• Variables
• func NewHandler(conf HandlerConfig) gin.HandlerFunc
• func Register(r *gin.RouterGroup) error
• func RegisterFor(r *gin.RouterGroup, configs ...Config) error
• type Config
  • func NewDefaultConfig() Config
  • func NewDefaultConfigFor(cs ...checks.Check) Config
• type FailureNotification
• type HandlerConfig
  • func NewDefaultHandlerConfig() HandlerConfig
  • func NewDefaultHandlerConfigFor(cs ...checks.Check) HandlerConfig

Examples

• Package (CustomHandler)
• Package (Register)
• Package (RegisterFor)

Variables

var (
	ErrHealthCheckFailed             = errors.New("health check failed")
	ErrHealthCheckNamesConflict      = errors.New("health check names conflict")
	ErrConfigsMethodEndpointConflict = errors.New("configs method and endpoint conflict")
	ErrEmptyConfigs                  = errors.New("empty configs")
)

Functions

func NewHandler

func NewHandler(conf HandlerConfig) gin.HandlerFunc

NewHandler creates a new health check handler that can be used to check if the application is running.

func Register

func Register(r *gin.RouterGroup) error

Register registers a default health check handler with the specified router group.

func RegisterFor

func RegisterFor(r *gin.RouterGroup, configs ...Config) error

RegisterFor registers one or more health check handlers with the specified router group and configurations.

Types

type Config

type Config struct {
	HTTPMethod string
	Endpoint   string
	HandlerConfig
}

Config represents the configuration for the health check.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates a new default health check configuration.

func NewDefaultConfigFor

func NewDefaultConfigFor(cs ...checks.Check) Config

NewDefaultConfigFor creates a new default health check configuration for the specified checks.

type FailureNotification

type FailureNotification struct {
	Threshold uint32
	Chan      chan error
}

FailureNotification represents the configuration for failure notifications.

type HandlerConfig

type HandlerConfig struct {
	Verbose  bool
	Excludes []string
	Checks   []checks.Check
	FailureNotification
}

HandlerConfig represents the configuration for the health check handler.

func NewDefaultHandlerConfig

func NewDefaultHandlerConfig() HandlerConfig

NewDefaultHandlerConfig creates a new default health check handler configuration.

func NewDefaultHandlerConfigFor

func NewDefaultHandlerConfigFor(cs ...checks.Check) HandlerConfig

NewDefaultHandlerConfigFor creates a new default health check handler configuration for the specified checks.