healthcheck

README

healthcheck

A very simple Docker Health Check helper.

Description

This small project can be used in Docker files to monitor the Docker container health by checking an HTTP GET endpoint. If the endpoint is not responsive within 2 seconds or returns an HTTP status code < 200, or an HTTP code > 299, the healthcheck executable (hc) will end with exit code 1. Otherwise, exit code 0 is used.

Usage

Download the executable from here.

Binary usage:

hc <url to check>

 - url to check: the full HTTP GET endpoint address that will be queried
 - exit code: 0 on success, 1 on failure

Docker usage:

COPY --from=buildImage /build/hc /app/hc

HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 CMD [ "/app/hc", "http://www.url.to.check.com" ]

Health check service library

This project also provides a very simple health check library that can be used to set up the health check server.

This is an example of how to use the library:

package main

import "git.prolicht.digital/golib/healthcheck"

func main() {
	healthcheck.New().Start() // start a default health check service on port 11223, this function is async
	
	healthcheck.New().StartForeground(context.Background()) // start a default health check service on port 11223 in foreground

	healthcheck.New(healthcheck.WithCustomCheck(func() int {
		return 500 // this is the HTTP status code
	})).Start() // start a custom health check service

	healthcheck.New(healthcheck.ListenOn(":8080"), healthcheck.WithCustomCheck(func() int {
		return 500
	})).Start() // start a custom health check service on port 8080
}

Using the healthcheck.ListenOnFromEnv() option reads the listening address from an environment variable. The default environment variable (HC_LISTEN_ADDR) name can be overridden by passing the name as argument: healthcheck.ListenOnFromEnv("THE_ENVIRONMENT_VARIABLE").

Documentation

Index

• func New(opts ...Option) *service
• type Option
  • func ListenOn(addr string) Option
  • func ListenOnFromEnv(envName ...string) Option
  • func WithCustomCheck(fnc func() int) Option

Functions

func New

func New(opts ...Option) *service

New creates a new healthcheck instance that can be started with either Start() or StartWithContext().

Types

type Option

type Option func(svc *service)

func ListenOn

func ListenOn(addr string) Option

ListenOn allows to change the default listening address of ":11223".

func ListenOnFromEnv

func ListenOnFromEnv(envName ...string) Option

ListenOnFromEnv sets the listening address to a value retrieved from the environment variable HC_LISTEN_ADDR. If the argument list is not empty, the listening address value will be loaded from an environment variable with the name of the first list entry. If the environment variable was empty, the listening address will not be overridden.

func WithCustomCheck

func WithCustomCheck(fnc func() int) Option

WithCustomCheck allows to use a custom check function. The integer return value of the check function is used as HTTP status code.