healthcheck-middleware
Version:
Express middleware for rendering a JSON healthcheck page.
152 lines (127 loc) • 4.94 kB
Markdown
[](https://travis-ci.org/michaelgoin/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.
```bash
$ npm install healthcheck-middleware
```
```js
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).
```js
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()`.
```js
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.
```js
fail();
```
> {status: 'failure'}
```js
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.
```js
pass();
```
> {status: 'success', uptime: 3, memoryUsage: {rss: 32587776, heapTotal: 29604500, heapUsed: 14572104}}
```js
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}}
```js
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.
```js
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'}
```js
module.exports = healthcheck({
healthInfo: function(passInfo) {
return 'This is not particularly helpful.'
}
});
```
> {message: 'This is not particularly helpful.'}
```js
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'}
```js
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'}