healthcheck

README

healthcheck

healthcheck is a package that supplies an http.Handler that reports whether your service is healthy or not. All you have to do is define a function that returns an error if one of your service's dependencies is unhealthy.

Using the package

Defining a check

To use the package, first we need to know if our service is healthy or not. A service is healthy if all the checks for it return no error. Let's define a new check:

type SQL struct {
	DB *sql.DB
	ID string
}

func (s SQL) Check(ctx context.Context) error {
	return s.DB.Ping()
}

func (s SQL) LogInfo(ctx context.Context) string {
	return s.ID
}

This check fulfills the healthcheck.Checker interface, by defining the Check method and the LogInfo method. The Check method returns nil if the check should be considered successful, or an error if it should be marked unhealthy. The LogInfo method returns information about the instance of the check (a database host, a connection string, or what have you) to uniquely identify the check in logs.

You can use the SQL check defined above by calling NewSQL from this package.

Setting up the http.Handler

Now that we have a check, we want an http.Handler that will return a 500 status code if the check fails, so we know something is wrong and our monitoring can alert.

For that, we use the NewChecks function:

// db is set up as an *sql.DB connection
sqlCheck := SQL{DB: db, ID: "mydb"}
handler := NewChecks(context.Background(), nil, sqlCheck)

handler is now an http.Handler, and will return a 500 status code if sqlCheck returns an error. You can set up as many checks on the handler as you like:

// db is set up as an *sql.DB connection
// otherdb is set up as a separate connection
sqlCheck := SQL{DB: db, ID: "mydb"}
otherCheck := SQL{DB: otherdb, ID: "myotherdb"}
handler := NewChecks(context.Background(), nil, sqlCheck, otherCheck)

Of course, it's not super useful to know that your service is unhealthy, but not know what the error was. To get that info, we need to pass a logging function. A logging function is anything that fills the func(message string, ...args interface{}) signature. You'll notice that log.Printf fits the bill. Let's use that.

// db is set up as an *sql.DB connection
// otherdb is set up as a separate connection
sqlCheck := SQL{DB: db, ID: "mydb"}
otherCheck := SQL{DB: otherdb, ID: "myotherdb"}
handler := NewChecks(context.Background(), log.Printf, sqlCheck, otherCheck)

Now the error that was returned that caused the 500 will be logged.

Documentation

Index

• type Checker
• type Checks
  • func NewChecks(ctx context.Context, logger func(format string, msg ...interface{}), ...) Checks
  • func (c Checks) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type SQL
  • func NewSQL(db *sql.DB, id string) SQL
  • func (s SQL) Check(ctx context.Context) error
  • func (s SQL) LogInfo(ctx context.Context) string

Types

type Checker

type Checker interface {
	Check(ctx context.Context) error
	LogInfo(ctx context.Context) string
}

Checker defines the methods necessary to determine if a certain aspect of a service should be considered healthy. If the Check function returns nil, the instance is healthy. Otherwise, it's unhealthy. The LogInfo method should return a string that contains debug information or other useful identifying information for the log output when Check returns an error.

type Checks

type Checks struct {
	Checks []Checker
	// This property will be deprecated once Go 1.7 is released
	Context context.Context
	Logger  func(format string, msg ...interface{})
}

Checks defines a group of Checkers, a log function to write their errors with, and a context to associate with the Checkers. Checks is an http.Handler.

func NewChecks

func NewChecks(ctx context.Context, logger func(format string, msg ...interface{}), checks ...Checker) Checks

NewChecks returns a Checks instance using the passed context, logging function, and Checkers.

func (Checks) ServeHTTP

func (c Checks) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP fulfills the http.Handler interface. Calling ServeHTTP will call the Check method on all the Checkers associated with the Checks. If any of the Checkers returns an error, a response with status 500 is written and the error is logged. Otherwise, a response with status 200 is written, and the text "OK" is written to the response.

type SQL

type SQL struct {
	DB *sql.DB
	ID string
}

SQL is a type that fills the Checker interface for an *sql.DB. ID is used as the identifying information returned by LogInfo, which is useful if more than one *sql.DB is needed for a service's health check.

func NewSQL

func NewSQL(db *sql.DB, id string) SQL

NewSQL returns an SQL instance using the passed *sql.DB and identifier.

func (SQL) Check

func (s SQL) Check(ctx context.Context) error

Check returns the output of the Ping method for the *sql.DB.

func (SQL) LogInfo

func (s SQL) LogInfo(ctx context.Context) string

LogInfo returns the ID string associated with the SQL it is called on. It should usually be set to a connection string, a database name, or anything else that would be useful to have in the log output.