vitals-node

vitals-node

Multi-framework health monitoring and system metrics for Node.js applications. Supports NestJS, Express, and Bun with zero-config setup.

Features

• ✅ Multi-framework support - NestJS, Express, and Bun
• ✅ Real-time dashboard - Beautiful UI with charts and dark mode
• ✅ System metrics - CPU, Memory, Disk monitoring
• ✅ Alert notifications - LINE, Email, Telegram
• ✅ Prometheus export - Ready for Grafana/Prometheus
• ✅ Prisma integration - Database query monitoring
• ✅ TypeScript first - Full type safety
• ✅ Zero config setup - Works out of the box
• ✅ Thai timezone support - Asia/Bangkok by default

Installation

npm install vitals-node
# or
yarn add vitals-node
# or
pnpm add vitals-node
# or
bun add vitals-node

Quick Start

Express.js

import express from 'express';
import { expressPulse } from 'vitals-node/express';

const app = express();

app.use('/health', expressPulse({
  dashboard: true,
  alerts: {
    line: { token: process.env.LINE_NOTIFY_TOKEN }
  }
}));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Dashboard: http://localhost:3000/health/dashboard');
});

NestJS

import { Module } from '@nestjs/common';
import { NestPulseModule } from 'vitals-node';

@Module({
  imports: [
    NestPulseModule.forRoot({
      path: '/health',
      dashboard: true,
      alerts: {
        line: { token: process.env.LINE_NOTIFY_TOKEN }
      }
    })
  ]
})
export class AppModule {}

Bun

import { bunPulse } from 'vitals-node/bun';

const pulse = bunPulse({ dashboard: true });

Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname.startsWith('/health')) {
      return pulse.handler(req);
    }
    return new Response('OK');
  }
});

Endpoints

Endpoint	Description
GET /health	Basic health status (JSON)
GET /health/detailed	Full metrics with health checks
GET /health/dashboard	Real-time HTML dashboard
GET /health/metrics	Prometheus format metrics
GET /health/history	Metrics history
GET /health/alerts	Alert history
POST /health/test-alerts	Test notification channels

Configuration

interface VitalsConfig {
  // Base path for health endpoints (default: '/health')
  path?: string;

  // Enable dashboard UI (default: true)
  dashboard?: boolean;

  // Metrics collection interval in ms (default: 5000)
  collectInterval?: number;

  // Timezone for display (default: 'Asia/Bangkok')
  timezone?: string;

  // Enable Prometheus export (default: true)
  prometheus?: boolean;

  // Alert configuration
  alerts?: {
    // Alert thresholds
    thresholds?: {
      cpu?: number;      // Default: 80%
      memory?: number;   // Default: 90%
      disk?: number;     // Default: 85%
      responseTime?: number; // Default: 3000ms
    };

    // Cooldown between alerts (default: 5 minutes)
    cooldown?: number;

    // LINE Notify
    line?: {
      token: string;
      enabled?: boolean;
    };

    // Email (SMTP)
    email?: {
      host: string;
      port: number;
      secure?: boolean;
      user: string;
      password: string;
      from: string;
      to: string[];
      enabled?: boolean;
    };

    // Telegram
    telegram?: {
      botToken: string;
      chatId: string;
      enabled?: boolean;
    };
  };

  // Custom health checks
  healthChecks?: HealthCheckDefinition[];
}

System Metrics

The metrics response includes:

{
  cpu: {
    usage: 45.5,        // Current CPU usage %
    cores: 8,           // Number of CPU cores
    model: "Intel...",  // CPU model name
    speed: 3.2          // CPU speed in GHz
  },
  memory: {
    total: 16384,       // Total memory in MB
    used: 8192,         // Used memory in MB
    free: 8192,         // Free memory in MB
    percentage: 50      // Usage percentage
  },
  disk: {
    total: 512000,      // Total disk in MB
    used: 256000,       // Used disk in MB
    free: 256000,       // Free disk in MB
    percentage: 50      // Usage percentage
  },
  process: {
    uptime: 86400,      // Process uptime in seconds
    pid: 1234,          // Process ID
    nodeVersion: "v20.0.0",
    memoryUsage: 128,   // Process memory in MB
    cpuUsage: 2.5       // Process CPU usage %
  }
}

Prisma Integration

Monitor database queries with Prisma middleware:

import { PrismaClient } from '@prisma/client';
import { prismaMiddleware, createPrismaHealthCheck } from 'vitals-node/prisma';
import { getMonitor } from 'vitals-node/core';

const prisma = new PrismaClient();

// Add middleware for query monitoring
prisma.$use(prismaMiddleware({
  slowQueryThreshold: 1000,  // Alert on queries > 1s
  logSlowQueries: true
}));

// Add database health check
const monitor = getMonitor();
monitor.addHealthCheck(createPrismaHealthCheck(prisma));

Database metrics include:

• Connection status
• Total query count
• Slow query count
• Average query time

Custom Health Checks

Add your own health checks:

import { createMonitor } from 'vitals-node/core';

const monitor = createMonitor();

monitor.addHealthCheck({
  name: 'redis',
  critical: true,
  timeout: 5000,
  check: async () => {
    const start = Date.now();
    try {
      await redis.ping();
      return {
        name: 'redis',
        status: 'healthy',
        responseTime: Date.now() - start,
        message: 'Redis connection OK'
      };
    } catch (error) {
      return {
        name: 'redis',
        status: 'unhealthy',
        responseTime: Date.now() - start,
        error: error.message
      };
    }
  }
});

await monitor.start();

Event Handling

Subscribe to monitoring events:

import { getMonitor } from 'vitals-node/core';

const monitor = getMonitor();

// Subscribe to metrics collection
monitor.on('metrics:collected', (event) => {
  console.log('Metrics:', event.data);
});

// Subscribe to alerts
monitor.on('alert:triggered', (event) => {
  console.log('Alert!', event.data);
});

Available events:

• metrics:collected - New metrics collected
• alert:triggered - Alert threshold exceeded
• alert:resolved - Alert condition resolved
• health:changed - Health status changed
• database:slow-query - Slow query detected
• database:error - Database error occurred

Prometheus / Grafana

The /health/metrics endpoint exports Prometheus-compatible metrics:

# HELP vitals_cpu_usage_percent Current CPU usage percentage
# TYPE vitals_cpu_usage_percent gauge
vitals_cpu_usage_percent 45.5

# HELP vitals_memory_usage_percent Memory usage percentage
# TYPE vitals_memory_usage_percent gauge
vitals_memory_usage_percent 62.3

# ... more metrics

Add to your Prometheus config:

scrape_configs:
  - job_name: 'my-app'
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/health/metrics'

Dashboard

The built-in dashboard provides:

• Real-time metrics display (auto-refresh every 5s)
• CPU/Memory charts (last 24 hours)
• System information
• Process details
• Health check status
• Alert history
• Dark/Light mode toggle
• Responsive design
• Thai timezone (Asia/Bangkok)

Access at: http://your-server/health/dashboard

Alert Configuration

LINE Notify

• Get a token from LINE Notify
• Configure:

alerts: {
  line: {
    token: 'YOUR_LINE_NOTIFY_TOKEN',
    enabled: true
  }
}

Telegram

• Create a bot with @BotFather
• Get your chat ID
• Configure:

alerts: {
  telegram: {
    botToken: 'YOUR_BOT_TOKEN',
    chatId: 'YOUR_CHAT_ID',
    enabled: true
  }
}

Email (SMTP)

alerts: {
  email: {
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    user: '[e-mail]',
    password: 'your-app-password',
    from: '[e-mail]',
    to: ['[e-mail]'],
    enabled: true
  }
}

API Reference

Express

import { expressPulse, createExpressRouter } from 'vitals-node/express';

// As middleware
app.use('/health', expressPulse(options));

// As router
const router = createExpressRouter(options);
app.use('/health', router);

NestJS

import { NestPulseModule, PulseService } from 'vitals-node';

// In module
NestPulseModule.forRoot(options)

// Async configuration
NestPulseModule.forRootAsync({
  useFactory: (configService) => ({
    alerts: {
      line: { token: configService.get('LINE_TOKEN') }
    }
  }),
  inject: [ConfigService]
})

// Inject service
constructor(private pulseService: PulseService) {}

Bun

import { bunPulse, withBunPulse } from 'vitals-node/bun';

// Manual handler
const pulse = bunPulse(options);
pulse.handler(req);

// Wrapper
Bun.serve(withBunPulse({
  ...options,
  fetch(req) {
    return new Response('OK');
  }
}));

Core (Standalone)

import { createMonitor, getMonitor } from 'vitals-node/core';

const monitor = createMonitor(options);
await monitor.start();

// Get metrics
const metrics = await monitor.getMetrics();
const health = await monitor.getHealth();
const detailed = await monitor.getDetailedHealth();

// Prometheus export
const prometheusText = await monitor.getPrometheusMetrics();

// Dashboard HTML
const html = monitor.getDashboardHtml();

// History
const history = monitor.getHistory(3600000); // Last hour

// Stop
monitor.stop();

Examples

See the examples folder for complete examples:

• Express Example
• NestJS Example
• Bun Example

Requirements

• Node.js 18+ or Bun 1.0+
• TypeScript 5+ (recommended)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.