@visulima/health-check

Visulima health-check

A library built to provide support for defining service health for node services. It allows you to register async health checks for your dependencies and the service itself, provides a health endpoint that exposes their status, and health metrics.

It’s built on top of

pingman, node:http, cacheable-lookup, node:process.env

_{Built with ❤︎ by Daniel Bannert}

Installation

npm install @visulima/health-check

yarn add @visulima/health-check

pnpm add @visulima/health-check

Usecases for API health check endpoints

Keeping the API health check endpoints generic allows to use them for multiple purposes. In this section, we will review of the everyday use cases of an API health check endpoint

Container orchestrators and API load balancers can use API health check endpoint to find out about the process status
Usage of memory, disk, and other server resources can be monitored via API health check endpoints
Health checks can test APIs dependencies, such as databases and external service endpoints, to confirm availability and normal functioning.

Usage

import { healthCheckHandler, HealthCheck as HealthCheck, nodeEnvironmentCheck } from "@visulima/health-check";

const HealthCheckService = new HealthCheck();

HealthCheckService.addChecker("node-env", nodeEnvironmentCheck);

export default healthCheckHandler(HealthCheckService); // returns a http handler

API health check endpoint types

There are at least three different types of API health check endpoints designed to serve specific purposes.

The readiness endpoint, often available via /health/ready, returns the readiness state to accept incoming requests from the gateway or the upstream proxy. Readiness signals that the app is running normally but isn’t ready to receive requests yet.
The liveness endpoint, often available via /health/live, returns the liveness of a microservice. If the check does not return the expected response, it means that the process is unhealthy or dead and should be replaced as soon as possible.
The generic health check endpoint, often available via /health, returns the status of the service and the dependencies.

Consider the following example: an API that loads JSON-based data into memory to serve requests.

The /health/ready continues to respond with NOT_READY signal while the API is loading the JSON file since the API cannot serve any request without the file in memory. Therefore, it may take time for the API to process the entire file.

The /health/live immediately signals LIVE, even though the app is not ready, to prevent the container orchestrator layer from restarting the app.

Consider protecting your health check endpoint

Most ping endpoints are publicly available because they don’t provide much internal or sensitive information. On the other hand, API health check endpoints expose information about your service, so it’s a good idea to protect this endpoint. You only need to make sure that your API monitoring tool supports sending API access keys.

Built-in Checks

The library comes with a set of built-in checks. Currently implemented checks are as follows:

Node Environment Check

This check verifies that the node environment is set to production. This check is useful for ensuring that the node environment is set to production in production environments or only that the NODE_ENV is set.

import { nodeEnvironmentCheck } from "@visulima/health-check";

nodeEnvironmentCheck(); // check if NODE_ENV is set
nodeEnvironmentCheck("production"); // check if NODE_ENV is set to production

HTTP built-in check

The HTTP check allows you to trigger an HTTP request to one of your dependencies, and verify the response status, and optionally the content of the response body.

import { httpCheck } from "@visulima/health-check";

httpCheck("https://example.com", {
    fetchOptions: {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
        },
        // ... any other options you want to pass to node-fetch
    },
    expected: {
        status: 200,
        body: "OK",
    },
});

DNS built-in check(s)

The DNS checks allow you to perform lookup to a given hostname / domain name / CNAME / etc, and validate that it resolves to at least the minimum number of required results.

import { dnsCheck } from "@visulima/health-check";

dnsCheck("example.com", ["1.1.1.1"], {
    family: "all",
    // ... other options for cacheable-lookup
});

Ping built-in check(s)

The ping checks allow you to verifies that a resource is still alive and reachable. For example, you can use it as a DB ping check to verify that your DB is still alive and reachable.

import { pingCheck } from "@visulima/health-check";

pingCheck("example.com", {
    timeout: 1000,
    // ... other options for pingman
});

Custom Checks

The library provides Check interface that you can implement to create your own custom checks.

type Checker = () => Promise<HealthReportEntry>;

/**
 * Shape of health report entry. Each checker must
 * return an object with similar shape.
 */
type HealthReportEntry = {
    displayName: string;
    health: {
        healthy: boolean;
        message?: string;
        timestamp: string;
    };
    meta?: any;
};

Expose Health Endpoint

The library provides an HTTP handler function for serving health stats in JSON format. You can register it using your favorite HTTP implementation like so:

import { handleHealthCheck } from "@visulima/health-check";

export default handleHealthCheck();

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

License

The visulima health-check is open-sourced software licensed under the MIT

@visulima/health-check