exframe-health Module

A framework for setting up health checks within microservices and its dependencies. Currently supports separate probes for "liveness" and "readiness" states, available with Kubernetes. When used in combination with exframe-service and exframe-rest, the necessary GET health routes will be automatically added when the microservice starts.

Features

• Custom creaton of health checks where the built in health check doesn't meet requirements.
• Probes for both "liveness" and "readiness"
• "Promotable" health checks that can dynamically affect liveness and/or readiness based on time certain parameters

Usage

const health = require('exframe-health');
health.add('check-1', () => {
  return isHealthy
    ? { status: 200, message: 'OK' }
    : { status: 503, message: 'Unhealthy' };
})

Methods

add()

Syntax

health.add(dependency, check, options)

Parameter Values

• dependency {string} Required - Unique name of the dependency being checked.

• check {function} Required - Function that tests the availability of the dependency (examples below)

• options {object}

  • checkType {string} - Type of health check to add. Valid values are:
    • "Promotable" Default - Health check can affect Liveness and/or Readiness probes (configuration options below).
    • "Liveness" - Health check will only affect the Liveness probe
    • "Readiness" - Health check will only affect the Readiness probe
  • promotionType {string} - Method for promoting a health check of type "Promotable". Valid values are:
    • "Timeout" Default - A failing health check will initially only affect the Readiness probe for the number of milliseconds specified in options.livenessPromotionTimeout after which the Liveness probe will also be affected.
    • "UserControlled" - The probe type currently executing is passed as an argument to the check function and left to the user what status should be returned for the given check.
  • livenessPromotionTimeout Number of milliseconds to wait before a failing health check affects the Liveness probe. Default is 0, meaning Liveness and Readiness probes will have the same status for the health check.

Examples

Create a custom health check. The custom health check should return a promise. Whether the promise is resolved or rejected, a json object should be returned containing (at a minimum) a status and a message. Other optional keys can be added as necessary. Any status of 400 or greater will result in the parent service being declared unhealthy.

const mongoose = require('mongoose');
const checkMongoose = () => {
  if (mongoose.connection.readyState === 1) {
    return Promise.resolve({
      status: 200,
      message: 'OK'
    });
  } else {
    return Promise.reject({
      status: 503,
      message: 'Service Unavailable'
    });
  }
};
health.add('MongoDB', checkMongoose);

Create a user-controlled, promotable health check.

const health = require('exframe-health');

const checkWorkQueue = (probeType) => async {
  if (queue.failed) {
    return { status: 503, message: 'Queue processing failed' };
  } else if (queue.size > 10 && probeType === health.ProbeTypes.Readiness) {
    return { status: 503, message: 'Queue limit exceeded' };
  } else {
    return { status: 200, message: 'OK' };
  }
};

health.add('checkWorkQueue-1', checkWorkQueue, {
  promotionType: health.PromotionTypes.UserControlled
});

get()

Syntax

health.get()

Returns a json object representing the health checks that have been added to the module.

remove()

Syntax

health.remove(dependency)

Removes a healthcheck from the module.

check

Syntax

health.check(req, res)