httphealth

README

httphealth

Simplistic pluggable HTTP server for reporting application and container health status

Building

go get github.com/moensch/httphealth

Standalone server

go get github.com/moensch/httphealth/cmd/httphealthd

Usage

Health checks written in go (preferred)

package main

import (
        "github.com/moensch/httphealth"
        "fmt"
        "os"
)


func main() {
        srv, err := httphealth.NewHttpHealth()
        if err != nil {
                fmt.Println(err)
                os.Exit(1)
        }

        srv.RegisterCheck("pidactive", IsPidActive)
        srv.RegisterCheck("thisfails", FailingCheck)
        srv.RegisterCachingCheck("cachethis", SomeCheck, 300)

        srv.Run()
}

func IsPidActive() httphealth.CheckResponse {
        resp := httphealth.CheckResponse{}

        p, err := os.FindProcess(13755)

        if err != nil {
                resp.Status = httphealth.STATUS_CRITICAL
                resp.Text = err.Error()

                return resp
        }

        resp.Status = httphealth.STATUS_OK
        resp.Text = strconv.Itoa(p.Pid)

        return resp
}

func FailingCheck() httphealth.CheckResponse {
        resp := httphealth.CheckResponse{
                Status: httphealth.STATUS_CRITICAL,
                Text:   "Some error message",
        }

        return resp
}

func SomeCheck() httphealth.CheckResponse {
        resp := httphealth.CheckResponse{
                Status: httphealth.STATUS_WARN,
                Text:   "this failed and is cached for 300 seconds",
        }

        return resp
}

Using Standalone server

If you don't want to write your checks in Go, you can use shell commands as checks too. Any non-zero exit code is considered a failure. All commands are run through /bin/sh -c.

You can use configuration file defined checks and check functions together.

cache: Duration string as defined here: https://golang.org/pkg/time/#ParseDuration

By default, no results are cached.

[listen]
port = 9000
address = "0.0.0.0"

[checks]

[checks.apache]
command = "ps aux | grep [h]ttp"
cache = "5m"

[checks.failcmd]
command = "/bin/false"

Running

#> httphealthd -c /etc/yourconf.toml

Command line arguments

-p Listen port (overrides config /listen/port) -l Listen address (overrides config /listen/address) -c Configuration file path (default search paths: /etc/httphealth.toml, /httphealth.toml)

Querying

Response Codes: 250 All checks passed 503 One or more checks are not STATUS_OK 404 Only used when running single check, and check not found

Run all checks

curl -s localhost:9000

Response

{
    "cachethis": {
        "cache_ttl": 142,
        "cache_used": true,
        "status": "warning",
        "status_code": 1,
        "text": "this failed and is cached for 300 seconds"
    },
    "failing": {
        "cache_ttl": 0,
        "cache_used": false,
        "status": "critical",
        "status_code": 2,
        "text": "Some error message"
    },
    "pidactive": {
        "cache_ttl": 0,
        "cache_used": false,
        "status": "ok",
        "status_code": 0,
        "text": "13755"
    }
}

Run single check

curl -s localhost:9000/checks/pidactive

Response

{
    "cache_ttl": 0,
    "cache_used": false,
    "status": "ok",
    "status_code": 0,
    "text": "13755"
}

List checks

curl -s localhost:9000/checks

Response

pidactive
failing
cachethis

Documentation

Index

• Constants
• Variables
• type Cache
  • func (c *Cache) Delete(name string)
  • func (c *Cache) Get(name string) (CheckResponse, int64, error)
  • func (c *Cache) Set(name string, resp CheckResponse, ttl int64)
• type CacheEntry
  • func (e *CacheEntry) Expires() int64
  • func (e *CacheEntry) ValidFor() int64
• type Check
• type CheckEntry
  • func (e *CheckEntry) Run() CheckResponse
• type CheckFunc
  • func (f CheckFunc) Run() CheckResponse
• type CheckResponse
  • func (resp *CheckResponse) IsCritical() bool
  • func (resp *CheckResponse) IsOk() bool
  • func (resp *CheckResponse) IsUnknown() bool
  • func (resp *CheckResponse) IsWarn() bool
  • func (resp CheckResponse) MarshalJSON() ([]byte, error)
  • func (resp *CheckResponse) StatusText() string
• type HealthCheck
• type HttpHealth
  • func NewHttpHealth() (*HttpHealth, error)
  • func (h *HttpHealth) HandleChecks(w http.ResponseWriter, r *http.Request)
  • func (h *HttpHealth) LoadConfig(path string) error
  • func (h *HttpHealth) Register(name string, check Check, cacheTtl int64)
  • func (h *HttpHealth) RegisterCachingCheck(name string, check func() CheckResponse, ttl int64) error
  • func (h *HttpHealth) RegisterCheck(name string, check func() CheckResponse) error
  • func (h *HttpHealth) Run()
  • func (h *HttpHealth) RunAllChecks(w http.ResponseWriter, r *http.Request)
  • func (h *HttpHealth) RunCheck(w http.ResponseWriter, r *http.Request, checkname string)

Constants

const (
	STATUS_OK       = 0
	STATUS_WARN     = 1
	STATUS_CRITICAL = 2
	STATUS_UNKNOWN  = 3
)

Variables

var (
	CheckCache    Cache
	ListenPort    int
	ListenAddress string
	ConfigFile    string
)

Types

type Cache

type Cache struct {
	Entries map[string]CacheEntry
}

func (*Cache) Delete

func (c *Cache) Delete(name string)

func (*Cache) Get

func (c *Cache) Get(name string) (CheckResponse, int64, error)

func (*Cache) Set

func (c *Cache) Set(name string, resp CheckResponse, ttl int64)

type CacheEntry

type CacheEntry struct {
	Name     string
	Response CheckResponse
	Ttl      int64
	Created  int64
}

func (*CacheEntry) Expires

func (e *CacheEntry) Expires() int64

func (*CacheEntry) ValidFor

func (e *CacheEntry) ValidFor() int64

type Check

type Check interface {
	Run() CheckResponse
}

type CheckEntry

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

func (*CheckEntry) Run

func (e *CheckEntry) Run() CheckResponse

type CheckFunc

type CheckFunc func() CheckResponse

func (CheckFunc) Run

func (f CheckFunc) Run() CheckResponse

type CheckResponse

type CheckResponse struct {
	Text      string
	Status    int
	FromCache bool
	CacheTtl  int64
}

func (*CheckResponse) IsCritical

func (resp *CheckResponse) IsCritical() bool

func (*CheckResponse) IsOk

func (resp *CheckResponse) IsOk() bool

func (*CheckResponse) IsUnknown

func (resp *CheckResponse) IsUnknown() bool

func (*CheckResponse) IsWarn

func (resp *CheckResponse) IsWarn() bool

func (CheckResponse) MarshalJSON

func (resp CheckResponse) MarshalJSON() ([]byte, error)

func (*CheckResponse) StatusText

func (resp *CheckResponse) StatusText() string

type HealthCheck

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

type HttpHealth

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

func NewHttpHealth

func NewHttpHealth() (*HttpHealth, error)

func (*HttpHealth) HandleChecks

func (h *HttpHealth) HandleChecks(w http.ResponseWriter, r *http.Request)

func (*HttpHealth) LoadConfig

func (h *HttpHealth) LoadConfig(path string) error

func (*HttpHealth) Register

func (h *HttpHealth) Register(name string, check Check, cacheTtl int64)

func (*HttpHealth) RegisterCachingCheck

func (h *HttpHealth) RegisterCachingCheck(name string, check func() CheckResponse, ttl int64) error

func (*HttpHealth) RegisterCheck

func (h *HttpHealth) RegisterCheck(name string, check func() CheckResponse) error

func (*HttpHealth) Run

func (h *HttpHealth) Run()

func (*HttpHealth) RunAllChecks

func (h *HttpHealth) RunAllChecks(w http.ResponseWriter, r *http.Request)

func (*HttpHealth) RunCheck

func (h *HttpHealth) RunCheck(w http.ResponseWriter, r *http.Request, checkname string)