Express middleware for rendering a JSON healthcheck page. Provides default functionality, ability to add additional checks and ability to change displayed health info.
$ npm install healthcheck-middleware
var healthcheck = require('healthcheck-middleware');
Returns healthcheck middleware using the given options. The middleware will return a JSON response with status 200 on success or status 500 on addChecks
failure (see addChecks).
app.use('/healthcheck', healthcheck());
{status: 'success', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}
These properties can be passed as a part of the options
object:
addChecks
healthInfo
A function that allows the addition of checks to the healthcheck. The function is called as addChecks(fail, pass)
. You will call fail()
or pass()
depending on your desired state.
addChecks will also catch a thrown Error but the preferred method is to call fail()
.
module.exports = healthcheck({
addChecks: function(fail, pass) {
store.getDatabaseInfoAsync()
.then(function(databaseInfo) {
pass(databaseInfo);
})
.catch(function() {
fail(new Error('could not connect to database'));
});
}
});
Call fail()
when the intent is the for the healthcheck to fail. Fail accepts an Error as an argument. Calling fail will result in a status 500 and a JSON message indicating failure with the error message.
fail();
{status: 'failure'}
fail(new Error('some error'));
{status: 'failure', message: 'some error'}
Call pass()
when the intent is for the healthcheck to pass. Pass can be called with a JSON object that specifies additional properties to display with the health information. Calling pass will result in a status 200 and JSON message that indicates success, process.uptime(), process.memoryUsage(), and any custom properties.
If you return properties called status, uptime or memoryUsage they will override the standard values returned.
pass();
{status: 'success', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}
var databaseInfo = {
region: 'us-west',
status: 'ACTIVE'
};
pass({database: databaseInfo});
{database: {region: 'us-west', status: 'ACTIVE'}, status: 'success', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}
pass({status: 'WORKED!'});
{status: 'WORKED!', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}
A function that allows customization of the displayed health information. The function is called as healthInfo(passInfo)
. The passInfo
parameter contains the health information that would normally be displayed (see examples above). You will return the JSON representation of the health info you want rendered. You may also return a string which will be converted into a JSON object {message: string}
.
Healthcheck will still result in a status 200 if an Error is thrown inside of healthInfo
. It will return a successful status with a warning that includes the error message.
module.exports = healthcheck({
healthInfo: function(passInfo) {
return {
status: passInfo.status,
server: os.hostname(),
version: process.env.APP_VERSION
};
}
});
{status: 'success', server: 'theServer', version: '1.0.0'}
module.exports = healthcheck({
healthInfo: function(passInfo) {
return 'This is not particularly helpful.'
}
});
{message: 'This is not particularly helpful.'}
module.exports = healthcheck({
healthInfo: function(passInfo) {
throw new Error('format fail');
}
});
{status: 'success', warning: 'Healthcheck passed but there was an error in healthInfo: format fail'}
module.exports = healthcheck({
addChecks: function(fail, pass) {
store.getDatabaseInfoAsync()
.then(function(databaseInfo) {
pass(databaseInfo);
})
.catch(function() {
fail(new Error('could not connect to database'));
});
},
healthInfo: function(passInfo) {
return {
status: passInfo.status,
server: os.hostname(),
version: process.env.APP_VERSION,
databaseRegion: passInfo.database.region,
databaseStatus: passInfo.database.status
};
}
});
{status: 'success', server: 'theServer', version: '1.0.0', databaseRegion: 'us-west', databaseStatus: 'ACTIVE'}