Documentation ¶
Overview ¶
Package healthcheck helps you implement Kubernetes liveness and readiness checks for your application. It supports synchronous and asynchronous (background) checks. It can optionally report each check's status as a set of Prometheus gauge metrics for cluster-wide monitoring and alerting. It even contains a handler with gRPC support.
It also includes a small library of generic checks for DNS, TCP, and HTTP reachability as well as Goroutine usage.
Example ¶
package main import ( "fmt" "net/http" "net/http/httptest" "net/http/httputil" "strings" "time" "github.com/GlobalWebIndex/healthcheck/checks" "github.com/GlobalWebIndex/healthcheck/handlers" ) func main() { // Create a Handler that we can use to register liveness and readiness checks. health := handlers.NewHandler() // Add a readiness check to make sure an upstream dependency resolves in DNS. // If this fails we don't want to receive requests, but we shouldn't be // restarted or rescheduled. upstreamHost := "upstream.example.com" err := health.AddReadinessCheck( "upstream-dep-dns", checks.DNSResolveCheck(upstreamHost, 50*time.Millisecond)) if err != nil { panic("`health.AddReadinessCheck()` failed") } // Add a liveness check to detect Goroutine leaks. If this fails we want // to be restarted/rescheduled. err = health.AddLivenessCheck("goroutine-threshold", checks.GoroutineCountCheck(100)) if err != nil { panic("`health.AddLivenessCheck()` failed") } // Serve http://0.0.0.0:8080/live and http://0.0.0.0:8080/ready endpoints. // go http.ListenAndServe("0.0.0.0:8080", health) // Make a request to the readiness endpoint and print the response. fmt.Print(dumpRequest(health, "GET", "/ready")) } func dumpRequest(handler http.Handler, method string, path string) string { req, err := http.NewRequest(method, path, nil) if err != nil { panic(err) } rr := httptest.NewRecorder() handler.ServeHTTP(rr, req) dump, err := httputil.DumpResponse(rr.Result(), true) if err != nil { panic(err) } return strings.Replace(string(dump), "\r\n", "\n", -1) }
Output: HTTP/1.1 503 Service Unavailable Connection: close Content-Type: application/json; charset=utf-8 {}
Example (Advanced) ¶
package main import ( "fmt" "net/http" "net/http/httptest" "net/http/httputil" "strings" "time" "github.com/GlobalWebIndex/healthcheck/checks" "github.com/GlobalWebIndex/healthcheck/handlers" ) func main() { // Create a Handler that we can use to register liveness and readiness checks. health := handlers.NewHandler() // Make sure we can connect to an upstream dependency over TCP in less than // 50ms. Run this check asynchronously in the background every 10 seconds // instead of every time the /ready or /live endpoints are hit. // // Async is useful whenever a check is expensive (especially if it causes // load on upstream services). upstreamAddr := "upstream.example.com:5432" err := health.AddReadinessCheck( "upstream-dep-tcp", checks.Async(checks.TCPDialCheck(upstreamAddr, 50*time.Millisecond), 10*time.Second)) if err != nil { panic("`health.AddReadinessCheck()` failed") } // Add a readiness check against the health of an upstream HTTP dependency upstreamURL := "http://upstream-svc.example.com:8080/healthy" err = health.AddReadinessCheck( "upstream-dep-http", checks.HTTPGetCheck(upstreamURL, 500*time.Millisecond)) if err != nil { panic("`health.AddReadinessCheck()` failed") } // Implement a custom check with a 50 millisecond timeout. err = health.AddLivenessCheck("custom-check-with-timeout", checks.Timeout(func() error { // Simulate some work that could take a long time time.Sleep(time.Millisecond * 100) return nil }, 50*time.Millisecond)) if err != nil { panic("`health.AddLivenessCheck()` failed") } // Expose the readiness endpoints on a custom path /healthz mixed into // our main application mux. mux := http.NewServeMux() mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello, world!")) }) mux.HandleFunc("/healthz", health.ReadyEndpoint) // Sleep for just a moment to make sure our Async handler had a chance to run time.Sleep(500 * time.Millisecond) // Make a sample request to the /healthz endpoint and print the response. fmt.Println(dumpRequest(mux, "GET", "/healthz")) } func dumpRequest(handler http.Handler, method string, path string) string { req, err := http.NewRequest(method, path, nil) if err != nil { panic(err) } rr := httptest.NewRecorder() handler.ServeHTTP(rr, req) dump, err := httputil.DumpResponse(rr.Result(), true) if err != nil { panic(err) } return strings.Replace(string(dump), "\r\n", "\n", -1) }
Output: HTTP/1.1 503 Service Unavailable Connection: close Content-Type: application/json; charset=utf-8 {}
Example (Database) ¶
// Connect to a database/sql database database := connectToDatabase() // Create a Handler that we can use to register liveness and readiness checks. health := handlers.NewHandler() // Add a readiness check to we don't receive requests unless we can reach // the database with a ping in <1 second. err := health.AddReadinessCheck("database", checks.DatabaseSelectCheck(database, 1*time.Second)) if err != nil { panic("`health.AddReadinessCheck()` failed") } // Serve http://0.0.0.0:8080/live and http://0.0.0.0:8080/ready endpoints. // go http.ListenAndServe("0.0.0.0:8080", health) // Make a request to the readiness endpoint and print the response. fmt.Print(dumpRequest(health, "GET", "/ready?full=1"))
Output: HTTP/1.1 200 OK Connection: close Content-Type: application/json; charset=utf-8 { "database": "OK" }
Example (Metrics) ¶
package main import ( "fmt" "net/http" "net/http/httptest" "net/http/httputil" "strings" "github.com/GlobalWebIndex/healthcheck/handlers" "github.com/prometheus/client_golang/prometheus" "github.com/prometheus/client_golang/prometheus/promhttp" ) func main() { // Create a new Prometheus registry (you'd likely already have one of these). registry := prometheus.NewRegistry() // Create a metrics-exposing Handler for the Prometheus registry // The healthcheck related metrics will be prefixed with the provided namespace health := handlers.NewMetricsHandler(registry, "example") // Add a simple readiness check that always fails. err := health.AddReadinessCheck("failing-check", func() error { return fmt.Errorf("example failure") }) if err != nil { panic("`health.AddReadinessCheck()` failed") } // Add a liveness check that always succeeds err = health.AddLivenessCheck("successful-check", func() error { return nil }) if err != nil { panic("`health.AddLivenessCheck()` failed") } // Create an "admin" listener on 0.0.0.0:9402 adminMux := http.NewServeMux() // go http.ListenAndServe("0.0.0.0:9402", adminMux) // Expose prometheus metrics on /metrics adminMux.Handle("/metrics", promhttp.HandlerFor(registry, promhttp.HandlerOpts{})) // Expose a liveness check on /live adminMux.HandleFunc("/live", health.LiveEndpoint) // Expose a readiness check on /ready adminMux.HandleFunc("/ready", health.ReadyEndpoint) // Make a request to the metrics endpoint and print the response. fmt.Println(dumpRequest(adminMux, "GET", "/metrics")) } func dumpRequest(handler http.Handler, method string, path string) string { req, err := http.NewRequest(method, path, nil) if err != nil { panic(err) } rr := httptest.NewRecorder() handler.ServeHTTP(rr, req) dump, err := httputil.DumpResponse(rr.Result(), true) if err != nil { panic(err) } return strings.Replace(string(dump), "\r\n", "\n", -1) }
Output: HTTP/1.1 200 OK Connection: close Content-Type: text/plain; version=0.0.4; charset=utf-8 # HELP example_healthcheck_status Current check status (0 indicates success, 1 indicates failure) # TYPE example_healthcheck_status gauge example_healthcheck_status{check="failing-check"} 1 example_healthcheck_status{check="successful-check"} 0
Click to show internal directories.
Click to hide internal directories.