pms_md 1.0.0

package/node-monitor/SETUP_GUIDE.md

@@ -0,0 +1,479 @@
+# 📘 Node Monitor - Complete Setup Guide
+
+This guide will walk you through setting up Node Monitor in your application step by step.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Email Notifications Setup](#email-notifications-setup)
+3. [Slack Notifications Setup](#slack-notifications-setup)
+4. [Database Monitoring Setup](#database-monitoring-setup)
+5. [Production Deployment](#production-deployment)
+6. [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+### Step 1: Install the Package
+
+```bash
+npm install @projectmd/node-monitor
+```
+
+### Step 2: Install Peer Dependencies
+
+Install only what you need:
+
+```bash
+# If using Express (required for most features)
+npm install express
+
+# If monitoring MongoDB
+npm install mongoose
+
+# If monitoring PostgreSQL
+npm install pg
+
+# If monitoring MySQL
+npm install mysql2
+
+# If monitoring Redis
+npm install ioredis
+```
+
+### Step 3: Create Configuration File
+
+Create a `.env` file in your project root:
+
+```bash
+cp node_modules/@projectmd/node-monitor/.env.example .env
+```
+
+Edit the `.env` file with your settings.
+
+---
+
+## Email Notifications Setup
+
+### Option 1: Gmail
+
+1. **Enable 2-Factor Authentication** on your Gmail account
+2. **Generate App Password**:
+   - Go to Google Account Settings → Security
+   - Under "Signing in to Google", select "App passwords"
+   - Generate a new app password for "Mail"
+3. **Configure in .env**:
+
+```env
+MONITOR_EMAIL_ENABLED=true
+MONITOR_EMAIL_HOST=smtp.gmail.com
+MONITOR_EMAIL_PORT=587
+MONITOR_EMAIL_SECURE=false
+MONITOR_EMAIL_USER=your-email@gmail.com
+MONITOR_EMAIL_PASS=your-16-char-app-password
+MONITOR_EMAIL_FROM=your-email@gmail.com
+MONITOR_EMAIL_RECIPIENTS=admin@example.com,ops@example.com
+```
+
+### Option 2: SendGrid
+
+```env
+MONITOR_EMAIL_ENABLED=true
+MONITOR_EMAIL_HOST=smtp.sendgrid.net
+MONITOR_EMAIL_PORT=587
+MONITOR_EMAIL_USER=apikey
+MONITOR_EMAIL_PASS=your-sendgrid-api-key
+MONITOR_EMAIL_FROM=noreply@yourdomain.com
+MONITOR_EMAIL_RECIPIENTS=admin@example.com
+```
+
+### Option 3: AWS SES
+
+```env
+MONITOR_EMAIL_ENABLED=true
+MONITOR_EMAIL_HOST=email-smtp.us-east-1.amazonaws.com
+MONITOR_EMAIL_PORT=587
+MONITOR_EMAIL_USER=your-smtp-username
+MONITOR_EMAIL_PASS=your-smtp-password
+MONITOR_EMAIL_FROM=noreply@yourdomain.com
+MONITOR_EMAIL_RECIPIENTS=admin@example.com
+```
+
+### Test Email Configuration
+
+```javascript
+const monitor = new NodeMonitor();
+
+// Send test email
+await monitor.notify('info', 'Test Email', 'This is a test notification');
+```
+
+---
+
+## Slack Notifications Setup
+
+### Step 1: Create Slack Incoming Webhook
+
+1. Go to https://api.slack.com/apps
+2. Click "Create New App" → "From scratch"
+3. Name your app (e.g., "Node Monitor") and select your workspace
+4. In the app settings, go to "Incoming Webhooks"
+5. Activate Incoming Webhooks
+6. Click "Add New Webhook to Workspace"
+7. Select the channel where you want notifications
+8. Copy the Webhook URL
+
+### Step 2: Configure in .env
+
+```env
+MONITOR_SLACK_ENABLED=true
+MONITOR_SLACK_WEBHOOK=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX
+MONITOR_SLACK_CHANNEL=#monitoring
+MONITOR_SLACK_USERNAME=Node Monitor
+```
+
+### Step 3: Test Slack Integration
+
+```javascript
+const monitor = new NodeMonitor();
+
+// Send test message
+await monitor.notify('info', 'Test Slack', 'Slack integration is working!');
+```
+
+---
+
+## Database Monitoring Setup
+
+### MongoDB with Mongoose
+
+```javascript
+const mongoose = require('mongoose');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+const monitor = new NodeMonitor();
+
+// Connect to MongoDB
+await mongoose.connect('mongodb://localhost:27017/myapp', {
+  useNewUrlParser: true,
+  useUnifiedTopology: true
+});
+
+// Register for monitoring
+monitor.registerDatabase('mongodb', 'mongoose', mongoose.connection);
+
+// Start monitoring
+monitor.start();
+```
+
+### PostgreSQL
+
+```javascript
+const { Pool } = require('pg');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+const monitor = new NodeMonitor();
+
+// Create connection pool
+const pool = new Pool({
+  host: 'localhost',
+  port: 5432,
+  database: 'myapp',
+  user: 'postgres',
+  password: 'password',
+  max: 20
+});
+
+// Register for monitoring
+monitor.registerDatabase('postgres', 'postgresql', pool, 'SELECT 1');
+
+// Start monitoring
+monitor.start();
+```
+
+### MySQL
+
+```javascript
+const mysql = require('mysql2/promise');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+const monitor = new NodeMonitor();
+
+// Create connection pool
+const pool = mysql.createPool({
+  host: 'localhost',
+  user: 'root',
+  password: 'password',
+  database: 'myapp',
+  waitForConnections: true,
+  connectionLimit: 10
+});
+
+// Register for monitoring
+monitor.registerDatabase('mysql', 'mysql', pool, 'SELECT 1');
+
+// Start monitoring
+monitor.start();
+```
+
+### Redis
+
+```javascript
+const Redis = require('ioredis');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+const monitor = new NodeMonitor();
+
+// Create Redis client
+const redis = new Redis({
+  host: 'localhost',
+  port: 6379,
+  password: 'your-password'
+});
+
+// Register for monitoring
+monitor.registerDatabase('redis', 'redis', redis);
+
+// Start monitoring
+monitor.start();
+```
+
+---
+
+## Production Deployment
+
+### 1. Environment Configuration
+
+Create separate `.env` files for each environment:
+
+```
+.env.development
+.env.staging
+.env.production
+```
+
+Load the appropriate file:
+
+```javascript
+require('dotenv').config({ 
+  path: `.env.${process.env.NODE_ENV || 'development'}` 
+});
+```
+
+### 2. Recommended Production Settings
+
+```env
+NODE_ENV=production
+
+# More frequent checks in production
+MONITOR_HEALTH_INTERVAL=30000
+MONITOR_SYSTEM_INTERVAL=60000
+MONITOR_DATABASE_INTERVAL=60000
+
+# Stricter thresholds
+MONITOR_CPU_THRESHOLD=75
+MONITOR_MEMORY_THRESHOLD=85
+MONITOR_ERROR_RATE_THRESHOLD=25
+
+# Enable all notifications
+MONITOR_EMAIL_ENABLED=true
+MONITOR_SLACK_ENABLED=true
+
+# Structured logging
+MONITOR_LOG_FORMAT=json
+MONITOR_LOG_LEVEL=info
+MONITOR_LOG_CONSOLE=false
+
+# Shorter cooldown for critical issues
+MONITOR_NOTIFICATION_COOLDOWN=180000
+```
+
+### 3. Process Manager (PM2)
+
+Create `ecosystem.config.js`:
+
+```javascript
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './server.js',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env: {
+      NODE_ENV: 'production'
+    },
+    error_file: './logs/pm2-error.log',
+    out_file: './logs/pm2-out.log',
+    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
+  }]
+};
+```
+
+Start with PM2:
+
+```bash
+pm2 start ecosystem.config.js
+pm2 save
+pm2 startup
+```
+
+### 4. Docker Deployment
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["node", "server.js"]
+```
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    env_file:
+      - .env.production
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+```
+
+### 5. Health Check Integration
+
+For Kubernetes:
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 30
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /health/info
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+For Docker Compose:
+
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 40s
+```
+
+---
+
+## Troubleshooting
+
+### Email Notifications Not Working
+
+**Problem**: Emails are not being sent
+
+**Solutions**:
+1. Check SMTP credentials are correct
+2. Verify firewall allows outbound connections on port 587/465
+3. Check spam folder
+4. Enable less secure apps (Gmail) or use app passwords
+5. Check logs: `tail -f logs/error-*.log`
+
+### Slack Notifications Not Working
+
+**Problem**: Slack messages not appearing
+
+**Solutions**:
+1. Verify webhook URL is correct
+2. Check the webhook hasn't been revoked
+3. Ensure channel exists and bot has access
+4. Test webhook with curl:
+```bash
+curl -X POST -H 'Content-type: application/json' \
+  --data '{"text":"Test message"}' \
+  YOUR_WEBHOOK_URL
+```
+
+### High CPU/Memory Alerts
+
+**Problem**: Constant alerts about high resource usage
+
+**Solutions**:
+1. Increase thresholds if they're too strict
+2. Optimize your application code
+3. Scale horizontally (add more instances)
+4. Increase cooldown period to reduce alert frequency
+
+### Database Connection Monitoring Issues
+
+**Problem**: False positive database disconnection alerts
+
+**Solutions**:
+1. Increase `MONITOR_DB_QUERY_TIMEOUT`
+2. Check database server is accessible
+3. Verify connection pool settings
+4. Increase `MONITOR_CONSECUTIVE_FAILURES` threshold
+
+### Logs Growing Too Large
+
+**Problem**: Log files consuming too much disk space
+
+**Solutions**:
+1. Reduce `MONITOR_LOG_MAX_FILES` (e.g., from 14d to 7d)
+2. Reduce `MONITOR_LOG_MAX_SIZE` (e.g., from 20m to 10m)
+3. Set up log rotation with logrotate
+4. Use external logging service (CloudWatch, Datadog, etc.)
+
+### Performance Impact
+
+**Problem**: Monitoring affecting application performance
+
+**Solutions**:
+1. Increase monitoring intervals
+2. Disable `MONITOR_TRACK_EVENT_LOOP` if not needed
+3. Reduce log level to 'warn' or 'error' in production
+4. Disable console logging in production
+
+---
+
+## Getting Help
+
+- **GitHub Issues**: https://github.com/yourorg/node-monitor/issues
+- **Documentation**: See README.md
+- **Examples**: Check the `examples/` directory
+
+---
+
+## Next Steps
+
+1. ✅ Set up basic monitoring
+2. ✅ Configure notifications
+3. ✅ Add database monitoring
+4. ✅ Test in staging environment
+5. ✅ Deploy to production
+6. 📊 Monitor the dashboard regularly
+7. 🔧 Fine-tune thresholds based on your application's behavior
+