Merge pull request #30 from InVisionApp/dselans/docs-examples

elaborated on a few points; added an example for a custom check

README.md

@@ -35,14 +35,24 @@ This library:
 
 * Allows you to define how to check your dependencies.
 * Allows you to define warning and fatal thresholds.
-* Will run your dependency checks on a given interval, in the background.
-* Exposes a way for you to gather the check results in a *fast* and *thread-safe* manner to help determine the final status of your `/status` endpoint.
-* Comes bundled w/ a number of checkers for well-known dependencies such as `MySQL`, `PostgreSQL`, `Redis`, `HTTP`, `Mongo`.
+* Will run your dependency checks on a given interval, in the background. **[1]**
+* Exposes a way for you to gather the check results in a *fast* and *thread-safe* manner to help determine the final status of your `/status` endpoint. **[2]**
+* Comes bundled w/ [pre-built checkers](/checkers) for well-known dependencies such as `Redis`, `HTTP`.
 * Makes it simple to implement and provide your own checkers (by adhering to the checker interface).
 * Is test-friendly
     + Provides an easy way to disable dependency health checking.
     + Uses an interface for its dependencies, allowing you to insert fakes/mocks at test time.
 
+**[1]** Make sure to run your checks on a "sane" interval - ie. if you are checking your
+Redis dependency once every five minutes, your service is essentially running _blind_
+for about 4.59/5 minutes. Unless you have a really good reason, check your dependencies
+every X _seconds_, rather than X _minutes_.
+
+**[2]** `go-health` continuously writes dependency health state data and allows
+you to query that data via `.State()`. Alternatively, you can use one of the
+pre-built HTTP handlers for your `/healthcheck` endpoint (and thus not have to
+manually inspect the state data).
+
 ## Example
 
 For _full_ examples, look through the [examples dir](examples/)
@@ -87,6 +97,29 @@ h.Start()
 
 From here on, you can either configure an endpoint such as `/healthcheck` to use a built-in handler such as `handlers.NewJSONHandlerFunc()` or get the current health state of all your deps by traversing the data returned by `h.State()`.
 
+## Sample /healthcheck output
+Assuming you have configured `go-health` with two `HTTP` checkers, your `/healthcheck`
+output would look something like this:
+
+```json
+{
+    "details": {
+        "bad-check": {
+            "name": "bad-check",
+            "status": "failed",
+            "error": "Ran into error while performing 'GET' request: Get google.com: unsupported protocol scheme \"\"",
+            "check_time": "2017-12-30T16:20:13.732240871-08:00"
+        },
+        "good-check": {
+            "name": "good-check",
+            "status": "ok",
+            "check_time": "2017-12-30T16:20:13.80109931-08:00"
+        }
+    },
+    "status": "ok"
+}
+```
+
 ## Additional Documentation
 * [Examples](/examples)
 * [Checkers](/checkers)

examples/custom-checker-server/custom-checker-server.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/InVisionApp/go-health"
+	"github.com/InVisionApp/go-health/handlers"
+)
+
+type CustomCheck struct{}
+
+func main() {
+	// Create a new health instance
+	h := health.New()
+
+	// Instantiate your custom check
+	customCheck := &CustomCheck{}
+
+	// Add the checks to the health instance
+	h.AddChecks([]*health.Config{
+		{
+			Name:     "good-check",
+			Checker:  customCheck,
+			Interval: time.Duration(2) * time.Second,
+			Fatal:    true,
+		},
+	})
+
+	//  Start the healthcheck process
+	if err := h.Start(); err != nil {
+		log.Fatalf("Unable to start healthcheck: %v", err)
+	}
+
+	log.Println("Server listening on :8080")
+
+	// Define a healthcheck endpoint and use the built-in JSON handler
+	http.HandleFunc("/healthcheck", handlers.NewJSONHandlerFunc(h, nil))
+	http.ListenAndServe(":8080", nil)
+}
+
+// Satisfy the go-health.ICheckable interface
+func (c *CustomCheck) Status() (interface{}, error) {
+	// perform some sort of check
+	if false {
+		return nil, fmt.Errorf("Something major just broke")
+	}
+
+	// You can return additional information pertaining to the check as long
+	// as it can be JSON marshalled
+	return map[string]int{"foo": 123, "bar": 456}, nil
+}

examples/simple-http-server/simple-http-server.go

@@ -1,5 +1,3 @@
-// This is a simple example demonstrating the simplest steps necessary for
-// integrating the healthcheck lib into a basic HTTP service.
 package main
 
 import (