Origami Frontend Components & Services

Readme: node-health-check

Build health check functions which comply with the FT health check standard.

Table Of Contents

Usage

Requirements

Running the Health Check module requires Node.js 10.x and npm. You can install with:

npm install @financial-times/health-check

API Documentation

This library makes use of promises – familiarity is assumed in the rest of the API documentation. You'll also need to require the module with:

const HealthCheck = require('@financial-times/health-check');

new HealthCheck( [options] )

This function returns a new health check object. You can configure the health checks with an options object if you need to override any defaults.

const health = new HealthCheck({
    checks: [
        // ...
    ]
});

The given checks start polling immediately at the intervals that you specify. The returned instance has several methods for reading this data.

health.checks()

This returns a health check function that's compatible with the Express Web Service module. The returned function returns a promise which resolves to a JSON-friendly copy of the health check data.

Assuming you've already included Express and Express Web Service:

app.use(expressWebService({
    healthCheck: health.checks()
}));

health.gtg()

This returns a good-to-go function that's compatible with the Express Web Service module. The returned function returns a promise which resolves to either true or false.

false will be the resolved value if any of the health checks with severity 1 are failing.

Assuming you've already included Express and Express Web Service:

app.use(expressWebService({
    goodToGoTest: health.gtg()
}));

health.toJSON()

Get the health check output as an array that's safe for converting to JSON. You can use this if you don't intend on using the Express Web Service module.

health.stop()

This stops all of the checks from running. This is useful if the health checks are keeping the Node.js process open and you need it to close. E.g. after integration tests.

health.stop();

new HealthCheck.Check( [options] )

This class is used to create custom health checks. You'll need to extend this class in order to use it, and can pass instances directly into HealthCheck when you instantiate it. E.g.

class MyHealthCheck extends HealthCheck.Check {

    constructor(options) {
        super(options);
    }

    // Must return a promise
    run() {
        return new Promise(resolve => {
            // Must set these properties
            this.ok = true;
            this.checkOutput = '';
            this.lastUpdated = new Date();
            resolve();
        });
    }

}

See examples for more information, or look through lib/check for more classes which already extend the base Check class.

Options

The Health Check module can be configured with a variety of options, passed in as an object to the HealthCheck constructor. The available options are as follows:

Health Check Configurations

Each health check can be configured as an object. These follow the FT health check standard, which has more information, and there are examples available to help you out. No matter what type of check you're adding, there are some common required properties:

There are also some common optional properties:

Different types of check may have additional config properties. These are documented below.

Check Type: CPU

The cpu type accepts some additional configuration:

Check Type: Disk Space

The disk-space type accepts some additional configuration:

Check Type: Memory

The memory type accepts some additional configuration:

Check Type: Ping URL

The ping-url type requires some additional configuration:

Check Type: TCP/IP

The tcp-ip type requires some additional configuration:

Check Type: Graphite Threshold

The graphite-threshold type requires some additional configuration:

See examples for sample usage.

Examples

You can find example implementations of health checks in the examples folder of this repo:

Node Fetch

If a project is using node-fetch as a npm dependency, there is a potential gotcha to be aware of, as without having a response for a custom healthcheck in the body, it will introduce a memory leak that will build up over time and crash the app due to not having a response in place.

There is a work-around this is to implement. This would be to either put in a response.json or a response.text in the custom healthcheck like below:

const fetch = require('node-fetch');

class MyHealthCheck extends HealthCheck.Check {
    async run() {
        try {
            const response = await fetch('https://some.api-address.com', {
                method: 'GET',
                headers: {
                    'apikey': 'your api key here'
                }
            });

            if (response.status !== 200) {
                throw new Error('Unable to access API');
            }

            if (response.status === 200) {
                this.ok = true;
                this.checkOutput = 'OK';
                response.text(); // read the body so it can be garbage collected
            }

        } catch (error) {
            this.ok = false;
            this.checkOutput = error.toString();
        }
    }
}

Contributing

This module has a full suite of unit tests, and is verified with ESLint. You can use the following commands to check your code before opening a pull request.

make verify  # verify JavaScript code with ESLint
make test    # run the unit tests and check coverage

Publishing

New versions of the module are published automatically by CI when a new tag is created matching the pattern /v.*/.

Migration guide

State Major Version Last Minor Release Migration guide
✨ active 2 N/A migrate to v2
⚠ maintained 1 1.11 N/A

Contact

If you have any questions or comments about this module, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.

Status
active Origami v1 (Bower)
Switch component view

GitHub Repository