express-hc

express-hc is a simple Express middleware for health checks. It provides system metrics and allows you to run custom health checks in your Express application.

Installation

npm install express express-hc

Usage

const express = require('express');
const healthCheck = require('express-hc');

const app = express();

// Custom health check function (optional)
const customTest = async () => {
  // Example: Check database connectivity
  const dbConnected = true; // replace with actual check
  return {
    status: dbConnected ? 200 : 500,
    response: { dbConnected }
  };
};

// Exclude metrics if needed
const exclusions = ['cpu_usage'];

app.get('/health', healthCheck(customTest, exclusions));

app.listen(3000, () => console.log('Server running on port 3000'));

API

healthCheck(test, exclusions)

Middleware function for performing health checks.

Parameters

| Parameter | Type | Default | Description | | | ------------ | -------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | test | () => Promise<{ status: number, response: any }> | async () => ({ status: 200, response: {} }) | Optional async function to run custom health checks. Should return an object with status and response. | | | exclusions | `Array<string | "*">` | [] | Optional array of metric names to exclude from the health check. Use '*' to exclude all built-in metrics. |

Returns

A standard Express middleware function with the signature (req, res).

Response Object

The middleware responds with a JSON object containing:

• failedMetrics: Array of metric names that failed to be retrieved.

• testResponse: Response object returned by the custom test function.

• System metrics (if not excluded):

  • uptime: Server uptime in seconds.
  • mem_usage: Current memory usage from process.memoryUsage().
  • node_resourceusage: Resource usage statistics from process.resourceUsage().
  • cpu_usage: CPU usage statistics from process.cpuUsage().

Example Response

{
  "failedMetrics": [],
  "testResponse": { "dbConnected": true },
  "uptime": 123.45,
  "mem_usage": {
    "rss": 23456789,
    "heapTotal": 12345678,
    "heapUsed": 9876543,
    "external": 456789
  },
  "node_resourceusage": { /* resource usage stats */ },
  "cpu_usage": { "user": 12345, "system": 6789 }
}

Metrics

The middleware provides the following default metrics:

| Name | Description | | -------------------- | ------------------------------------------------------------- | | uptime | Server uptime in seconds (process.uptime()) | | mem_usage | Memory usage (process.memoryUsage()) | | node_resourceusage | Node.js resource usage statistics (process.resourceUsage()) | | cpu_usage | CPU usage statistics (process.cpuUsage()) |

Error Handling

If a metric fails to be retrieved, it is added to the failedMetrics array in the response. Errors are also logged to the console.

License

MIT © OroTeam