rfdickerson / healthcheck-proof-of-concept

Health Checking middleware for NodeJS applications

Health Checker

A proof-of-concept library for ExpressJS-based applications to add a health checking endpoint and provide a payload with information about the running application and the connected services.

Getting Started

Install with:

yarn add health-check

Add the following to your ExpressJS application:

// import the library
var healthcheck =  require("healthcheck");

You can set up your health checker is a custom health check callback:

// create a health checker
const healthChecker = new healthcheck.HealthChecker();
healthChecker.onCheck( () => {
  // do special checking
  return true;
});
// set up an endpoint at /health
this.app.use("/health", healthChecker.router);

Add Health Checking Services

Import the service checker for the service you want to check such as MongoDB, Redis, PostgreSQL, etc. Add the checker before the health check is invoked. You can create multiple service checkers of the same type but different identifiers.

The following example uses the Mongoose health checker against the MongoDB database connection:

// create a new Mongoose connection to MongoDB
mongoose.connect("mongodb://localhost/healthcheck");
// register the service checker with the Mongoose connection
const mongoDBCheck = new healthchecker.MongooseServiceChecker(mongoose.connection);
// choose a name for the service checker as 'mongo-1'
healthChecker.register("mongo-1", mongoDBCheck);

Health Checking Status

All applications will return the following basic payload at the registered health route, such as /health:

{
  "status": "UP",
  "uptime": 100567,
}

When other services are registered on the health checker, the following information can appear:

{
  "status": "UP",
  "uptime": 100567,
  "services": {
    "mongo":
      {
        "status": "UP",
      },
    "redis":
      {
        "status": "DOWN"
      }
  }
}

When there is an error, accompanying a DOWN state, the payload will typically contain an error message:

{
  "status": "DOWN",
  "errorMessage": "Could not bind to port 3000"
}

{
  "status": "DOWN",
  "errorMessage": "Could not connect to port 27017"
}

The application status can take the following values:

• UP: The application is up and operating normally
• DOWN: The application is down and not operating normally

The services status can take the following values:

• UP: The service is connected and operating normally
• DOWN: The service is not connected and perhaps not operating normally
• CONNECTING: Currently trying to establish a connection before moving to the connected state
• DISCONNECTING: Currently moving from the connected state to disconnected state.

The application uptime is reported in milliseconds from when the health check service was initialized.

LICENSE

IBM HealthCheck Copyright 2017 IBM

This product includes software developed at IBM.