NestJS Health Monitor

A comprehensive health monitoring package for NestJS applications with detailed metrics and Kubernetes-ready health checks.

Features

• Kubernetes-Ready Health Checks: Includes liveness and readiness probes for container orchestration
• Detailed System Metrics: Memory usage, CPU utilization, disk space, and system information
• Request Tracking: Monitor HTTP requests, response times, and status codes
• Historical Data: Track metrics over time with configurable history length
• Swagger Documentation: Auto-generated API documentation for all endpoints
• Flexible Configuration: Enable/disable specific monitoring features based on your needs
• Security: Optional password protection for sensitive monitoring endpoints

Installation

Using the CLI (Recommended)

# Install globally
npm install -g @texagon/nestjs-health

# Run the installer in your NestJS project directory
texagon-nestjs-health install

This will guide you through an interactive setup process.

Manual Installation

# Install the package
npm install @texagon/nestjs-health

# Install required peer dependencies if you don't have them
npm install @nestjs/terminus @nestjs/axios

Then add to your app.module.ts:

import { HealthModule } from '@texagon/nestjs-health';

@Module({
  imports: [
    // ... other imports
    HealthModule.register({
      enableMemoryMonitoring: true,
      enableDiskMonitoring: true,
      diskPath: '/',
      diskThresholdPercent: 0.75,
      routePrefix: 'health',
    }),
  ],
})
export class AppModule {}

Available Endpoints

• GET /health: General health check (returns 200 if healthy, 503 if unhealthy)
• GET /health/live: Liveness probe for Kubernetes
• GET /health/ready: Readiness probe for Kubernetes
• GET /health/stats: Detailed system metrics and statistics

Note: If password protection is enabled, all endpoints require authentication using Bearer token authentication. Add the header Authorization: Bearer yourpassword to your requests.

Detailed Statistics

The /health/stats endpoint provides detailed information including:

• Process Information: PID, uptime, memory usage
• System Information: Platform, architecture, node version, system uptime, load average
• Memory Usage: Current, minimum, and maximum memory usage
• CPU Utilization: Current and historical CPU usage
• Disk Information: Available disk space
• Request Metrics: Total request count, average response time, request breakdown by method and status code

Add the ?includeHistory=true query parameter to include historical metrics data.

Configuration Options

When registering the module, you can customize its behavior:

HealthModule.register({
  // Enable/disable memory monitoring (heap and RSS)
  enableMemoryMonitoring: true,
  
  // Enable/disable disk space monitoring
  enableDiskMonitoring: true,
  
  // Path to monitor for disk space
  diskPath: '/',
  
  // Threshold percentage for disk space warning (0.75 = 75%)
  diskThresholdPercent: 0.75,
  
  // Route prefix for health endpoints
  routePrefix: 'health',
  
  // Enable password protection for health endpoints
  passwordProtected: false,
  
  // Password for accessing health endpoints (required if passwordProtected is true)
  password: 'your-secure-password',
});

Docker / Kubernetes Integration

Add these health checks to your container configuration:

HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
  CMD wget -q -O- http://localhost:3000/health/live || exit 1

For Kubernetes, add to your deployment:

livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
  initialDelaySeconds: 15
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10

License

MIT