Health Actuator

A Spring Boot Actuator-like health monitoring library for Node.js. Automatically detects database and Redis connections and provides health check endpoints with zero configuration.

Features

• 🏥 Auto-Detection - Automatically detects MongoDB, PostgreSQL, MySQL, Prisma, Sequelize, and Redis connections
• 📊 Health Checks - Aggregate health status from all detected services
• 📈 Metrics - System and application metrics
• ℹ️ Info - Application information, environment variables, and system details
• 🔍 Liveness & Readiness - Kubernetes-ready probes

Installation

npm install @akshat001/health-actuator

Quick Start (Zero Configuration!)

import express from 'express';
import { useHealthActuator } from '@akshat001/health-actuator';

const app = express();

// That's it! Auto-detects DB and Redis, all endpoints available
useHealthActuator(app);

app.listen(3000);

Endpoints automatically available:

• GET /health - Full health check (shows DB, Redis status)
• GET /health/liveness - Liveness probe
• GET /health/readiness - Readiness probe
• GET /info - Application info + environment variables
• GET /metrics - System metrics

Auto-Detection

The library automatically detects:

Databases

• MongoDB (mongoose) - Detects mongoose.connection
• PostgreSQL (pg) - Detects global.pgPool
• MySQL (mysql2) - Detects global.mysqlPool
• Prisma - Detects PrismaClient instances
• Sequelize - Detects global.sequelize

Redis

• ioredis - Auto-detects ioredis clients
• node-redis - Detects global.redisClient

Manual Registration (Optional)

If auto-detection doesn't find your connections, register them manually:

import express from 'express';
import { 
  useHealthActuator, 
  registerPostgres, 
  registerRedis 
} from '@akshat001/health-actuator';
import { Pool } from 'pg';
import { createClient } from 'redis';

const app = express();

// Your database setup
const dbPool = new Pool({ /* config */ });
const redisClient = createClient({ /* config */ });

// Register connections (optional - auto-detection works for most cases)
registerPostgres(dbPool);
registerRedis(redisClient);

// Setup health actuator
useHealthActuator(app);

app.listen(3000);

Example Responses

Health Endpoint (GET /health)

{
  "status": "UP",
  "components": {
    "mongodb": {
      "status": "UP",
      "details": { "message": "Database connection is healthy" }
    },
    "ioredis": {
      "status": "UP",
      "details": { "message": "Redis connection is healthy", "ping": "PONG" }
    }
  },
  "timestamp": "2024-01-22T09:00:00.000Z"
}

Info Endpoint (GET /info)

{
  "app": {
    "name": "my-app",
    "version": "1.0.0",
    "node": "v20.0.0"
  },
  "system": {
    "platform": "linux",
    "arch": "x64",
    "hostname": "server-01",
    "cpus": 4,
    "totalMemory": 8589934592,
    "freeMemory": 4294967296
  },
  "environment": {
    "NODE_ENV": "production",
    "PORT": "3000",
    "DATABASE_URL": "***",
    "REDIS_URL": "***"
  }
}

Metrics Endpoint (GET /metrics)

{
  "uptime": {
    "name": "uptime",
    "value": 3600,
    "unit": "seconds"
  },
  "memory": {
    "heap": {
      "used": { "name": "memory.heap.used", "value": 1048576, "unit": "bytes" },
      "total": { "name": "memory.heap.total", "value": 2097152, "unit": "bytes" }
    }
  },
  "cpu": {
    "user": { "name": "cpu.user", "value": 123456, "unit": "microseconds" }
  }
}

Complete Example

// src/app.ts
import express from 'express';
import mongoose from 'mongoose';
import { useHealthActuator } from '@akshat001/health-actuator';

const app = express();

// Your database connection (mongoose will be auto-detected)
mongoose.connect('mongodb://localhost:27017/mydb');

// Your Redis connection (if using ioredis, will be auto-detected)
// const redis = new Redis('redis://localhost:6379');

// Setup health actuator - auto-detects mongoose and redis!
useHealthActuator(app);

// Your routes
app.get('/', (req, res) => {
  res.json({ message: 'Hello World' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Health: http://localhost:3000/health');
  console.log('Info: http://localhost:3000/info');
  console.log('Metrics: http://localhost:3000/metrics');
});

Custom Configuration (Optional)

import express from 'express';
import { useHealthActuator, CustomIndicator } from '@akshat001/health-actuator';

const app = express();

useHealthActuator(app, {
  basePath: '/actuator', // Custom base path
  customIndicators: [
    new CustomIndicator('external-api', async () => {
      const response = await fetch('https://api.example.com/health');
      return {
        status: response.ok ? 'UP' : 'DOWN',
        details: { statusCode: response.status }
      };
    })
  ]
});

app.listen(3000);

Environment Variables

You can configure via environment variables:

HEALTH_ACTUATOR_BASE_PATH=/actuator
HEALTH_ACTUATOR_ENABLE_HEALTH=true
HEALTH_ACTUATOR_ENABLE_METRICS=true

import { useHealthActuator, loadConfigFromEnv } from '@akshat001/health-actuator';

useHealthActuator(app, loadConfigFromEnv());

License

MIT