Watchdock NPM | npm.io

Watchdock 🔍

A powerful and flexible system monitoring library for Node.js applications with built-in support for multiple notification providers.

✨ Features

📊 System Metrics Monitoring
- CPU usage and load
- Memory utilization
- Disk space
- Process information
🚨 Multiple Notification Providers
- Discord webhooks
- Telegram bots
- Email notifications
⚙️ Advanced Configuration
- Customizable monitoring intervals
- Flexible threshold settings
- Duration-based alerts
- Custom metrics support
🛡️ Reliability
- Error handling
- Retry mechanisms
- Graceful failure handling

📦 Installation

# Using npm
npm install @raphab3/watchdock

# Using yarn
yarn add @raphab3/watchdock

# Using pnpm
pnpm add @raphab3/watchdock

🚀 Quick Start

import { SystemMonitor } from '@raphab3/watchdock';

const monitor = new SystemMonitor({
  interval: "*/5 * * * *", // Check every 5 minutes
  providers: [
    {
      type: "discord",
      webhookUrl: "your-discord-webhook-url"
    },
    {
      type: "telegram",
      botToken: "your-telegram-bot-token",
      chatId: "your-chat-id"
    }
  ],
  notifications: {
    cpu: {
      value: 80, // Notify when CPU > 80%
      duration: 5, // Must exceed for 5 minutes
      notify: true
    },
    memory: {
      value: 90, // Notify when memory > 90%
      notify: true
    },
    disk: {
      value: 95, // Notify when disk > 95%
      notify: true
    },
    status: {
      notifyOn: ["unhealthy", "degraded"] // Notify on these states
    }
  }
});

monitor.start();

📚 Configuration

Monitor Config Options

interface MonitorConfig {
  // Cron expression for monitoring interval
  interval: string;
  
  // Array of notification providers
  providers: NotificationConfig[];
  
  // Optional environment name
  env?: string;
  
  // Optional custom metrics collector
  customMetrics?: () => Promise<ApplicationMetrics>;
  
  // Notification rules
  notifications?: NotificationRules;
}

Notification Providers

Discord

{
  type: "discord",
  webhookUrl: "your-webhook-url",
  username?: "Custom Bot Name",
  avatarUrl?: "https://your-avatar-url.com/image.png"
}

{
  type: "telegram",
  botToken: "your-bot-token",
  chatId: "your-chat-id"
}

Email

{
  type: "email",
  host: "smtp.example.com",
  port: 587,
  secure: true,
  auth: {
    user: "your-email@example.com",
    pass: "your-password"
  },
  from: "monitor@example.com",
  to: ["admin@example.com"]
}

Custom Metrics

You can add your own application metrics:

const monitor = new SystemMonitor({
  // ... other config
  customMetrics: async () => ({
    activeConnections: await getActiveConnections(),
    requestCount: await getRequestCount(),
    errorRate: await calculateErrorRate(),
    responseTime: await getAverageResponseTime()
  })
});

📊 Metrics Format

The monitoring system collects and reports the following metrics:

interface MetricsReport {
  timestamp: string;
  status: "healthy" | "degraded" | "unhealthy";
  errors: string[];
  system: {
    cpu: {
      usage: number;
      count: number;
      loadAvg: number[];
    };
    memory: {
      total: number;
      free: number;
      used: number;
      heapTotal: number;
      heapUsed: number;
      external: number;
      rss: number;
    };
    disk: {
      total: number;
      free: number;
      used: number;
      usedPercentage: number;
    };
    process: {
      uptime: number;
      pid: number;
      version: string;
    };
  };
  application: ApplicationMetrics;
}

🔔 Notification Examples

Discord Notification

Discord Notification Example

Telegram Notification

Telegram Notification Example

🛠️ Advanced Usage

Custom Notification Rules

const monitor = new SystemMonitor({
  // ... other config
  notifications: {
    custom: [
      {
        condition: (metrics) => metrics.application.errorRate > 5,
        message: "Error rate exceeded 5%"
      },
      {
        condition: (metrics) => metrics.application.responseTime > 1000,
        message: "Average response time exceeded 1 second"
      }
    ]
  }
});

Duration-Based Alerts

notifications: {
  cpu: {
    value: 80,
    duration: 5, // Only alert if CPU > 80% for 5+ minutes
    notify: true
  }
}

📝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.