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

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




Methods

$3


Syntax
`javascript
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.

`javascript
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.

`javascript
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
});
`

$3

Syntax

`javascript
health.get()
`
Returns a json object representing the health checks that have been added to the module.

$3

Syntax

`javascript
health.remove(dependency)
`

Removes a healthcheck from the module.

$3

Syntax

`javascript
health.check(req, res)
``