HealthCheck

@justomx/healthcheck is a simple yet effective library designed to facilitate the monitoring of various components in your application. This tool is particularly useful in production environments, where the availability and performance of services are critical. With @justomx/healthcheck, you can implement health checks that evaluate the status of key components, such as disk space, network connectivity, and other external services, ensuring your application is functioning correctly.

Key Features

Disk Space Monitoring: Checks the available disk space, allowing you to proactively manage storage resources and prevent failures due to lack of space.
Connectivity Checks (Ping): Performs ping checks to specific IP addresses and domains to ensure your application can communicate with crucial external services.
Custom Health Checks: Enables developers to create custom health checks by implementing the HealthCheck interface, providing flexibility to assess other critical aspects of your application.
Easy Integration: Easily integrates into existing applications, including Express.js servers, facilitating the implementation of a health endpoint to monitor the application’s status in real-time.

Benefits

Implementing robust health checks is a best practice in modern application development. It allows for early detection and diagnosis of issues before they impact end-users, helping maintain the availability and reliability of your application. Additionally, by providing details about the status of individual components, you can make informed decisions about the maintenance and scalability of your infrastructure.

Installation

To install the library, run the following command in your terminal:

npm install --save @justomx/healthcheck

Features

Disk Space Healthcheck: Monitors available disk space.
Ping Healthcheck: Verifies connectivity to specific network addresses.
Custom Healthchecks: Create custom health checks by implementing the HealthCheck interface.

Disk Space Healthcheck

To create an instance of the DiskSpace class, use the following code:

import { DiskSpace } from "@justomx/healthcheck";

const diskSpace = DiskSpace.build();
const health = await diskSpace.test();

Custom Options

You can customize the disk space check by specifying options:

import { DiskSpace } from "@justomx/healthcheck";

const diskSpace = DiskSpace.build({
  // Specify the threshold as "kb", "mb", or "gb"
  threshold: "50mb",
  // Set to true to include details in the response
  showDetails: false,
});
const health = await diskSpace.test();

Default Parameter Values

Parameter	Default Value
threshold	`25mb`
showDetails	`true`

Ping Healthcheck (Disabled)

To create an instance of the Ping class, use the following code:

import { Ping } from "@justomx/healthcheck";

const ping = Ping.build();
const health = await ping.test();

Custom Options

You can customize the ping check by specifying options:

import { Ping } from "@justomx/healthcheck";

// Get a logger instance (e.g., from Bunyan)
const logger = getLogger();

const ping = Ping.build({
  // Specify target DNS addresses
  targets: ["8.8.8.8", "8.8.4.4"],
  // Set threshold to 50%
  threshold: 0.5,
  // Set to true to include details in the response
  showDetails: false,
  // Logger for debugging
  logger,
});
const health = await ping.test();

Default Parameter Values

Parameter	Default Value
targets	See Default Targets
threshold	`0.8` (80%)
showDetails	`true`
logger	`undefined`

Default Targets

The default targets used for ping checks include:

8.8.8.8: Google DNS primary
8.8.4.4: Google DNS secondary
1.1.1.1: Cloudflare DNS primary
1.0.0.1: Cloudflare DNS secondary

Custom Healthcheck

To create a custom health check, implement the HealthCheck interface as follows:

import { type HealthCheck, type Health } from "@justomx/healthcheck"

export class CustomHealthCheck implements HealthCheck {
  readonly kind: string = 'custom';
  async test(): Promise<Health> {
    return {
      status: 'Up',
      details: {
        hello: 'world!'
      }
    };
  }
  // The static method to build the health check is optional
  static build(): CustomHealthCheck {
    return new CustomHealthCheck();
  }
}

How to Use

Evaluating Health Checks

To evaluate multiple health checks simultaneously:

import check, { DiskSpace, Ping } from "@justomx/healthcheck";

const diskSpace = DiskSpace.build();
const ping = Ping.build();

const response = await check(diskSpace, ping);

Integrating with Express.js

To add a health check endpoint in an Express.js application, implement the following:

import express from "express";
import check, { DiskSpace, Ping } from "@justomx/healthcheck";

const app = express();
app.use(express.json({ limit: "15mb" }));
app.use(express.urlencoded({ extended: true }));

app.get("/health", async (_req, res) => {
  const ping = Ping.build();
  const diskSpace = DiskSpace.build();

  const data = await check(ping, diskSpace);
  return res.status(data.status === "Up" ? 200 : 500).json(data);
});

app.listen(8080, () => {
  console.log("⚡️ Server is running at http://localhost:8080");
});

Using Custom Healthcheck in Express.js

To utilize a custom health check, create an instance of your custom health check class and pass it to the check method:

app.get("/health", async (_req, res) => {
  const ping = Ping.build();
  const diskSpace = DiskSpace.build();
  const custom = new CustomHealthCheck();

  const data = await check(ping, diskSpace);
  const data = await check(ping, diskSpace, custom);
  return res.status(data.status === "Up" ? 200 : 500).json(data);
});

Example Response

The response from this Express.js implementation could look like this:

{
  "status": "Up",
  "components": {
    "ping": {
      "status": "Up",
      "details": {
        "rate": 1,
        "total": 9,
        "success": 9
      }
    },
    "diskSpace": {
      "status": "Up",
      "details": {
        "free": 26363060224,
        "total": 33552252928,
        "threshold": 26214400
      }
    },
    "custom": {
      "status": "Up",
      "details": {
        "hello": "world!"
      }
    }
  }
}