@texagon/nestjs-health/README.md

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

# 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)

```bash
# 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

```bash
# 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`:

```typescript
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:

```typescript
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:

```dockerfile
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:

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

## License

MIT