🐦 AlertSparrow

A lightweight Node.js package to monitor CPU, memory, load average, disk storage, and SSL certificate expiry, with customizable alerts.

✅ Currently Supported:

• Console alerts
• Telegram alerts

🚧 Coming Soon:

• Email alerts
• Slack alerts

📦 Installation

npm install alert-sparrow [email protected]

⚙️ Usage

Initialize and configure the monitor:

const AlertSparrow = require('alert-sparrow');

const monitor = new AlertSparrow({
  cpuThreshold: 0.9, // Alert if CPU usage > 90%
  loadThreshold: 4,  // Alert if 1-min load avg > 4
  memoryThreshold: 0.9, // Alert if memory usage > 90%
  diskThreshold: 0.1, // Alert if free disk < 10%
  sslExpiryDays: 7,   // Alert if SSL expires in <7 days
  pollInterval: 60000, // Check every 60s
  alertCooldown: 300000, // 5min cooldown between the *same* alert type
  diskPath: '/', // Disk path to monitor
  domains: ['example.com', 'yourdomain.com'], // Domains for SSL monitoring
  alertChannels: {
    telegram: { 
      botToken: 'your-telegram-bot-token',
      chatId: 'your-chat-id' 
    },
    email: {
      // Email alerts coming soon
    },
    slack: {
      // Slack alerts coming soon
    }
  }
});

// Start monitoring
monitor.start();

// Get real-time stats
console.log(monitor.getStats());

✉️ Receive Alerts

Alerts are sent via console and Telegram when thresholds are breached. If you configure Email or Slack, you'll see a "Coming soon" notice.

Example alert message in Telegram:

🐦🚨 AlertSparrow Notification

Type: CPU Details: CPU usage exceeded 90%: 95.23%

⏰ Time: 2025-07-09 13:00:00 UTC

📈 Retrieve Stats

Use monitor.getStats() to get current system metrics with human-readable formatting:

{
  "cpu": { "usage": "45.12%", "cores": 4 },
  "load": { "oneMin": "1.20", "fiveMin": "1.00", "fifteenMin": "0.80" },
  "memory": { "total": "16.00 GB", "free": "8.00 GB", "usage": "50.00%" },
  "disk": { "freePercent": "60.00%", "free": "100.00 GB", "total": "250.00 GB" },
  "ssl": { 
    "example.com": { 
      "expiry": "2025-12-01T12:00:00Z",
      "daysLeft": 145 
    }
  }
}

🌟 Features

• CPU Monitoring: Tracks per-core and average CPU usage.
• Load Average: Monitors 1, 5, and 15-minute load averages (Linux/macOS).
• Memory Monitoring: Tracks total and free memory.
• Disk Usage: Monitors free disk space on a specified path.
• SSL Expiry: Checks certificate expiry with retry logic.
• Alerts: Currently supports Telegram notifications. Email and Slack coming soon.
• Stats API: Retrieve real-time metrics with readable formatting.
• Lightweight: Minimal dependencies.
• Configurable: Custom thresholds, intervals, and domains.

📝 Notes

• Telegram: Create a bot via @BotFather to get your token and chat ID.
• Email: Email alerts are not yet supported.
• Slack: Slack alerts are not yet supported.
• Windows: Load average monitoring is unavailable.
• SSL Checks: Require internet access and valid HTTPS domains.
• Testing: Use expired.badssl.com to trigger SSL expiry alerts.

🛠️ Testing

Example domain to test SSL expiry:

expired.badssl.com

📄 License

MIT

🐦 AlertSparrow — Simple, flexible system monitoring.