Healthz

Code of Conduct |
Contribution Guidelines

This is a package that allows you to set up health checks for your services. By
default, the health checks will be available at the /_healthz endpoint but can
be configured with the Prefix and Endpoint variables.

By default, the health check package will add a single default test. This test
doesn’t validate anything, it simply returns no error.

Registering additional tests

If you want to add more tests in case your service/worker depends on a specific
set of tools (like a JWT key mounted on a volume), you can register a new test
as follows:

func init() {
    healthz.RegisterTest("jwt-key", jwtCheck)
}
func jwtCheck(ctx context.Context) error {
    _, err := os.Stat("/jwt/ecdsa-private.pem")
    return err
}

Attaching the endpoints to an existing server

If you have an existing server running, you can attach the /_healthz endpoint
to it without having to start a separate server.

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    handler := healthz.NewHandler(mux)
    http.ListenAndServe(":3000", handler)
}

This will create a new mux which listens to the /hello request. We then attach
the healthcheck handler by using healthz.NewHandler(mux).

Creating a standalone server

When your application isn’t a web server, but you still want to add health
checks, you can use the provided server implementation.

func main() {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt)
    srv := healthz.NewServer("0.0.0.0", 3000)
    go srv.Start()
    <-stop
    ctx, _ := context.WithTimeout(context.Background(), 5*time.Second)
    srv.Shutdown(ctx)
}

Using middleware

With both the NewHandler and NewServer implementation, we’ve provided a way
to add middleware. This allows you to add logging to your health checks for
example.

The middleware functions are respectively NewHandlerWithMiddleware and
NewServerWithMiddleware. They accept the arguments of their parent function
but also a set of middlewares as variadic arguments.

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    handler := healthz.NewHandlerWithMiddleware(mux, logMiddleware)
    http.ListenAndServe(":3000", handler)
}
func logMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        log.Print("start request")
        next.ServeHTTP(w, r)
        log.Print("end request")
    })
}

Output

On the health check endpoint, we return a set of values useful to us. Extending
the example from above, these are both return values (one where the file is
present, one where it isn’t).

200 OK

{
  "checked_at": "2017-11-22T14:18:50.339Z",
  "duration_ms": 0,
  "result": "success",
  "tests": {
    "default": {
      "duration_ms": 0,
      "result": "success"
    },
    "jwt-key": {
      "duration_ms": 0,
      "result": "success"
    }
  }
}

503 Service Unavailable

{
  "checked_at": "2017-11-22T14:18:50.339Z",
  "duration_ms": 1,
  "result": "failure",
  "tests": {
    "default": {
      "duration_ms": 0,
      "result": "success"
    },
    "jwt-key": {
      "duration_ms": 0,
      "result": "failure"
    }
  }
}

Middlewares

We’ve included a set of standard middlewares that can be useful for general use.

Cache

The cache middleware allows you to cache a response for a specific duration.
This prevents the health check to overload due to different sources asking for
the health status. This is especially useful when the health checks are used to
check the health of other services as well.

To use this middleware, simply add it to the chain:

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    handler := healthz.NewHandlerWithMiddleware(
        mux,
        healthz.CacheMiddleware(5*time.Second),
    )
    http.ListenAndServe(":3000", handler)
}