healthcheck-middleware

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');

healthcheck([options])

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}}

options

These properties can be passed as a part of the options object:

• addChecks
• healthInfo

addChecks

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'));
		});
	}
});

fail

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.

Example 1

fail();

{status: 'failure'}

Example 2

fail(new Error('some error'));

{status: 'failure', message: 'some error'}

pass

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.

Example 1

pass();

{status: 'success', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}

Example 2

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}}

Example 3

pass({status: 'WORKED!'});

{status: 'WORKED!', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}

healthInfo

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.

Example 1

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'}

Example 2

module.exports = healthcheck({
	healthInfo: function(passInfo) {
		return 'This is not particularly helpful.'
	}
});

{message: 'This is not particularly helpful.'}

Example 3

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'}

Full Example

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'}