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 inoptions.livenessPromotionTimeout
after which the Liveness probe will also be affected. -
"UserControlled"
- The probe type currently executing is passed as an argument to thecheck
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.
-
checkType
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)