healthcheck

README

healthcheck-go-sdk

This is library for implementing k8s health check with go-restful

It provides dependencies health checking which returns dependency info, health status, timestamp and last error information of the dependency check result.

What's new in v2

• Support soft and hard dependency option. AddHealthCheck defaults to soft and AddHardHealthCheck is available for registering a hard dependency. A soft dependency will not affect the overall healthy status of the service if the dependency is not healthy, meanwhile a hard dependency health will.
• Support background periodic check instead of immediate check on every /healthz request
• The /healthz response now returns last call time, last known good call time, and last error message of the corresponding dependency health check
• New UpdateHealth method to enable the implementer service to update a dependency health
• CheckFunc templates improvements

Usage

Installing

go get -u github.com/AccelByte/healthcheck-go-sdk/v2

NOTE: since the v2 includes eventstream-go-sdk v4 template check function, you will need to make sure that cgo is enabled (configurable with CGO_ENABLED=1 environment variable) and parsing -tags musl param when building your Go application in Alpine Linux.

Reference: https://github.com/AccelByte/eventstream-go-sdk#v4

Initiating

h := healthcheck.New(&healthcheck.Config{
ServiceName: "serviceName",
BasePath: "/servicePath"},
BackgroundCheckInterval: 60*time.Second,
})

Registering a (soft) dependency (recommended)

redisClient := new(redis.Client)
timeout := 5 * time.Second
h.AddHealthCheck("redis", "redis:6379", h.RedisHealthCheck(redisClient, timeout))

Registering a hard dependency

h.AddHardHealthCheck("other-dependency", "dependency:1234", func() error {
// do checking
return nil
})

Use periodic background checking (recommended)

h.StartBackgroundCheck(ctx)

Registering health check webservice to a go-restful container

serviceContainer := restful.NewContainer()
...
serviceContainer.Add(h.AddWebservice())

Methods for Updating Health Dependency

There are two ways for a dependency health to be updated.

The first one is by attaching a check function when adding a dependency using AddHealthCheck or AddHardHealthCheck as shown in the previous section. It suits well if the dependency already provides a way for doing health check, hence the check can be done easily inside the check function.

When a dependency does not provide a straight-forward way for health check and there is no easy workaround, we can use UpdateHealth instead to update the dependency health. The idea is to update the dependency health status right after the dependency is called.

h.AddHealthCheck("emailProvider", "https://email-provider", nil) // register dependency health check with nil check function

...

err := emailProvider.Send(from, to, emailBody)
if err != nil {
	_ = h.UpdateHealth("emailProvider", false, &healthcheck.CheckError{Timestamp: time.Now(), Message: err.Error()}) // update health to false with check error included
	return err
}

_ = h.UpdateHealth("emailProvider", true, nil) // update to healthy if succeed

Check Funtion Templates

Health check function templates are available at checks.go

Documentation

Index

• Constants
• type CheckError
• type CheckFunc
  • func CloudStorageCheck(cloudStorage commonblobgo.CloudStorage, ...) CheckFunc
  • func ElasticHealthCheck(elasticClient *elastic.Client, host, port string, timeout time.Duration) CheckFunc
  • func IamHealthCheck(iamClient iam.Client, requiredClientPermissions []iam.Permission) CheckFunc
  • func KafkaEventstreamV4HealthCheck(client eventstream.Client, topic string, timeout time.Duration) CheckFunc
  • func MongoHealthCheck(mongoClient *mongo.Client, timeout time.Duration, ...) CheckFunc
  • func PostgresHealthCheck(postgreClient *gorm.DB, timeout time.Duration, ...) CheckFunc
  • func PostgresHealthCheckV1(postgreClient *gormv1.DB, timeout time.Duration, ...) CheckFunc
  • func RedisHealthCheck(redisClient *redis.Client, timeout time.Duration, ...) CheckFunc
  • func UniversalRedisHealthCheck(redisClient redis.UniversalClient, timeout time.Duration, ...) CheckFunc
• type Config
• type Handler
  • func New(config *Config) Handler

Constants

const (
	DefaultBackgroundCheckInterval = 60 * time.Second
)

Types

type CheckError

type CheckError struct {
	Timestamp time.Time
	Message   string
}

CheckError holds error information result of a dependency check submitted via UpdateHealth API.

type CheckFunc

type CheckFunc func() error

func CloudStorageCheck

func CloudStorageCheck(cloudStorage commonblobgo.CloudStorage, additionalCheck ...func(cloudStorage commonblobgo.CloudStorage) error) CheckFunc

CloudStorageCheck is function for check cloud straoge health based on AccelByte common-blob-go library

func ElasticHealthCheck

func ElasticHealthCheck(elasticClient *elastic.Client, host, port string, timeout time.Duration) CheckFunc

ElasticHealthCheck is function for Elastic health check

func IamHealthCheck

func IamHealthCheck(iamClient iam.Client, requiredClientPermissions []iam.Permission) CheckFunc

IamHealthCheck is function for IAM health check. The requiredClientPermissions parameter is an optional parameter to check if the IAM client token has the specified permissions.

func KafkaEventstreamV4HealthCheck

func KafkaEventstreamV4HealthCheck(client eventstream.Client, topic string, timeout time.Duration) CheckFunc

KafkaEventstreamV4HealthCheck is health check for Kafka with eventstream-go-sdk v4 library.

func MongoHealthCheck

func MongoHealthCheck(mongoClient *mongo.Client, timeout time.Duration, additionalCheck ...func(mongoClient *mongo.Client) error) CheckFunc

MongoHealthCheck is function for mongodb health check

func PostgresHealthCheck

func PostgresHealthCheck(postgreClient *gorm.DB, timeout time.Duration, additionalCheck ...func(postgreClient *gorm.DB) error) CheckFunc

PostgresHealthCheck is health check for Postgres with gorm V2 driver

func PostgresHealthCheckV1

func PostgresHealthCheckV1(postgreClient *gormv1.DB, timeout time.Duration, additionalCheck ...func(postgreClient *gormv1.DB) error) CheckFunc

PostgresHealthCheckV1 is health check for Postgres with gorm V1 driver

func RedisHealthCheck

func RedisHealthCheck(redisClient *redis.Client, timeout time.Duration, additionalCheck ...func(redisClient *redis.Client) error) CheckFunc

RedisHealthCheck is function for Redis health check

func UniversalRedisHealthCheck

func UniversalRedisHealthCheck(redisClient redis.UniversalClient, timeout time.Duration,
	additionalCheck ...func(redisClient redis.UniversalClient) error) CheckFunc

UniversalRedisHealthCheck is function for Redis health check using Universal Redis (support cluster and standalone)

type Config

type Config struct {
	ServiceName             string
	BasePath                string
	BackgroundCheckInterval time.Duration
}

type Handler

type Handler interface {
	AddWebservice() []*restful.WebService
	AddWebserviceV1() []*restfulV1.WebService

	// AddHealthCheck adds a dependency health check. It will be a soft dependency check, hence if the check failed,
	// it will only return healthy=false on the corresponding dependency and will not affect the overall healthy status.
	AddHealthCheck(name, url string, check CheckFunc)

	// AddHardHealthCheck adds a hard dependency health check.
	// It will return healthy=false on the corresponding dependency and the overall healthy status.
	AddHardHealthCheck(name, url string, check CheckFunc)

	// StartBackgroundCheck starts a background health check worker. The health check will be performed at a
	// certain interval, specified in Config, rather than every health endpoint request.
	StartBackgroundCheck(ctx context.Context)

	// UpdateHealth updates a dependency health status. If you want to exclusively update a dependency health
	// using this, make sure to pass nil value onto check function param when adding the dependency using
	// AddHealthCheck or AddHardHealthCheck.
	UpdateHealth(name string, isHealthy bool, checkError *CheckError) error
}

func New

func New(config *Config) Handler