express-health-probe

A simple, enterprise-ready healthcheck middleware for Express.js.

Provides perfect /health, /ready, and /metrics endpoints instantly. Built for modern cloud-native architectures like Kubernetes, Docker Swarm, and AWS ECS.

🚀 Features

• Zero-Config Database Monitoring: Auto-detects Mongoose, Redis, and Postgres connections. No need to write custom ping functions!
• Prometheus Built-in: Automatically tracks and exports metrics for Grafana.
• Enterprise Safeguards: DDoS cache protection, automatic timeouts, and Graceful Shutdown signal trapping built in.
• TypeScript Ready: Full code autocomplete and type definitions included natively.

📦 Installation

npm install express-health-probe express

💻 Usage

1. Basic (1-line setup)

Instantly adds highly-performant /health, /ready, and /metrics routes to your app.

import express from 'express';
import healthcheck from 'express-health-probe';

const app = express();

app.use(healthcheck());

app.listen(3000);

2. Advanced (The "Magic" Auto-Dependency Check)

Want to check if MongoDB or Redis is alive before saying the app is ready? Just pass the clients into the dependencies object. The package handles picking the right ping commands for you automatically!

import express from 'express';
import healthcheck from 'express-health-probe';
import mongoose from 'mongoose';
import { createClient } from 'redis';

const app = express();
const redisClient = createClient();

app.use(healthcheck({
  dependencies: {
    mongo: mongoose.connection,
    redis: redisClient
  }
}));

3. Enterprise (Kubernetes & Hooks)

For production builds, cache the database checks, configure timeouts, and hook into Datadog/OpenTelemetry easily.

app.use(healthcheck({
  // Protect your database from being pinged too often
  cacheDuration: 10000, 
  timeout: 5000, 
  
  // Cleanly shut down if Kubernetes kills the pod
  gracefulShutdown: true,
  onShutdown: async () => {
    console.log("Shutting down cleanly...");
    await mongoose.connection.close();
  },

  // Log failures securely to APM tracing tools
  onCheckFail: ({ path, error, duration }) => {
    console.error(`Check ${path} failed in ${duration}ms! ${error.message}`);
  }
}));

⚙️ Configuration Options

| Option | Type | Default | Description | |---|---|---|---| | path | string | '/health' | Path for Liveness probe (Are you running?) | | readyPath | string | '/ready' | Path for Readiness probe (Are DBs connected?) | | metricsPath | string | '/metrics' | Path for Prometheus exports | | dependencies | Object | {} | Map of Mongo, Redis, or Postgres clients to auto-check | | cacheDuration | number | 0 | MS to cache successful checks (database protection) | | timeout | number | 5000 | MS before a readiness check forcibly fails | | gracefulShutdown | boolean| false | Enable Kubernetes SIGTERM / SIGINT trapping | | exposeStackTraces| boolean| false | Export exact Error trace messages in your JSON | | onShutdown | Function | | Hook fired when process terminates via Graceful Shutdown | | onCheckStart | Function | | Hook fired precisely when a healthcheck starts | | onCheckSuccess| Function | | Hook fired precisely when a healthcheck successfully completes | | onCheckFail | Function | | Hook fired when a healthcheck fails |

❤️ Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📄 License

MIT License