pms_md 1.0.0

package/node-monitor/GETTING_STARTED.md

@@ -0,0 +1,416 @@
+# 🚀 Getting Started with Node Monitor
+
+Welcome! This guide will help you get Node Monitor up and running in your application in just a few minutes.
+
+## Prerequisites
+
+- Node.js 14.0.0 or higher
+- An existing Express.js application (or willingness to create one)
+- Basic knowledge of Node.js and npm
+
+## Step-by-Step Guide
+
+### Step 1: Install Node Monitor
+
+```bash
+npm install @projectmd/node-monitor
+```
+
+If you're using Express (recommended):
+```bash
+npm install express
+```
+
+### Step 2: Create Your First Monitored App
+
+Create a file called `server.js`:
+
+```javascript
+const express = require('express');
+const NodeMonitor = require('@projectmd/node-monitor');
+
+// Initialize the monitor
+const monitor = new NodeMonitor({
+  app: {
+    name: 'My First Monitored App',
+    version: '1.0.0'
+  }
+});
+
+// Create Express app
+const app = express();
+app.use(express.json());
+
+// Add monitoring middleware
+app.use(monitor.requestLogger());
+
+// Add a health check endpoint
+app.get('/health', monitor.healthCheckEndpoint());
+
+// Your application routes
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello, World!' });
+});
+
+// Test error endpoint
+app.get('/error', (req, res, next) => {
+  const error = new Error('This is a test error');
+  error.statusCode = 500;
+  next(error);
+});
+
+// Error handling (MUST be last)
+app.use(monitor.notFoundHandler());
+app.use(monitor.errorMiddleware());
+
+// Start the server
+const server = app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+  
+  // Start monitoring
+  monitor.start();
+  
+  // Setup graceful shutdown
+  monitor.setupGracefulShutdown(server);
+});
+```
+
+### Step 3: Run Your App
+
+```bash
+node server.js
+```
+
+### Step 4: Test the Monitoring
+
+Open your browser or use curl:
+
+```bash
+# Check health
+curl http://localhost:3000/health
+
+# Test your app
+curl http://localhost:3000/
+
+# Trigger an error
+curl http://localhost:3000/error
+
+# Try a non-existent route (404)
+curl http://localhost:3000/nonexistent
+```
+
+### Step 5: Check the Logs
+
+Look in the `logs/` directory that was automatically created:
+
+```bash
+# View application logs
+cat logs/application-*.log
+
+# View error logs
+cat logs/error-*.log
+```
+
+## 🎉 Congratulations!
+
+You now have a monitored Node.js application! The monitor is:
+- ✅ Tracking all errors
+- ✅ Logging requests
+- ✅ Monitoring system resources
+- ✅ Providing health check endpoints
+
+## Next Steps
+
+### Add Email Notifications
+
+1. **Get Email Credentials** (Gmail example):
+   - Enable 2FA on your Gmail account
+   - Generate an App Password
+   - Copy the 16-character password
+
+2. **Update your code**:
+
+```javascript
+const monitor = new NodeMonitor({
+  app: {
+    name: 'My App',
+    version: '1.0.0'
+  },
+  notifications: {
+    email: {
+      enabled: true,
+      host: 'smtp.gmail.com',
+      port: 587,
+      auth: {
+        user: 'your-email@gmail.com',
+        pass: 'your-app-password'
+      },
+      from: 'your-email@gmail.com',
+      recipients: ['admin@example.com']
+    }
+  }
+});
+```
+
+3. **Test it**:
+
+```javascript
+// Add this route to test notifications
+app.post('/test-notification', async (req, res) => {
+  await monitor.notify('info', 'Test Alert', 'This is a test notification');
+  res.json({ message: 'Notification sent!' });
+});
+```
+
+### Add Slack Notifications
+
+1. **Create Slack Webhook**:
+   - Go to https://api.slack.com/apps
+   - Create a new app
+   - Enable Incoming Webhooks
+   - Add webhook to your workspace
+   - Copy the webhook URL
+
+2. **Update your code**:
+
+```javascript
+const monitor = new NodeMonitor({
+  notifications: {
+    slack: {
+      enabled: true,
+      webhook: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
+      channel: '#monitoring'
+    }
+  }
+});
+```
+
+### Monitor Your Database
+
+**MongoDB Example**:
+
+```javascript
+const mongoose = require('mongoose');
+
+// Connect to MongoDB
+await mongoose.connect('mongodb://localhost:27017/myapp');
+
+// Register for monitoring
+monitor.registerDatabase('mongodb', 'mongoose', mongoose.connection);
+```
+
+**PostgreSQL Example**:
+
+```javascript
+const { Pool } = require('pg');
+
+const pool = new Pool({
+  connectionString: 'postgresql://user:password@localhost:5432/myapp'
+});
+
+monitor.registerDatabase('postgres', 'postgresql', pool);
+```
+
+### Add Custom Health Checks
+
+```javascript
+// Check if external API is available
+monitor.registerHealthCheck('external-api', async () => {
+  try {
+    const response = await fetch('https://api.example.com/health');
+    return response.ok;
+  } catch {
+    return false;
+  }
+});
+
+// Check if cache is working
+monitor.registerHealthCheck('cache', async () => {
+  try {
+    await redis.ping();
+    return true;
+  } catch {
+    return false;
+  }
+});
+```
+
+### Use Environment Variables
+
+1. **Create `.env` file**:
+
+```env
+NODE_ENV=development
+MONITOR_APP_NAME=my-app
+
+# Email
+MONITOR_EMAIL_ENABLED=true
+MONITOR_EMAIL_USER=your-email@gmail.com
+MONITOR_EMAIL_PASS=your-app-password
+MONITOR_EMAIL_RECIPIENTS=admin@example.com
+
+# Slack
+MONITOR_SLACK_ENABLED=true
+MONITOR_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK
+
+# Thresholds
+MONITOR_CPU_THRESHOLD=80
+MONITOR_MEMORY_THRESHOLD=90
+```
+
+2. **Load environment variables**:
+
+```javascript
+require('dotenv').config();
+
+const monitor = new NodeMonitor();
+// Config is automatically loaded from environment variables
+```
+
+## Common Patterns
+
+### Pattern 1: Async Route Handlers
+
+```javascript
+app.get('/users', monitor.asyncHandler(async (req, res) => {
+  const users = await User.find();
+  res.json(users);
+}));
+```
+
+### Pattern 2: Custom Error Creation
+
+```javascript
+app.get('/user/:id', async (req, res, next) => {
+  const user = await User.findById(req.params.id);
+  
+  if (!user) {
+    const error = NodeMonitor.createError('User not found', 404);
+    return next(error);
+  }
+  
+  res.json(user);
+});
+```
+
+### Pattern 3: Manual Logging
+
+```javascript
+app.post('/payment', async (req, res) => {
+  try {
+    const result = await processPayment(req.body);
+    
+    monitor.logInfo('Payment processed successfully', {
+      amount: req.body.amount,
+      userId: req.user.id
+    });
+    
+    res.json(result);
+  } catch (error) {
+    monitor.logError('payment_failed', error.message, {
+      amount: req.body.amount,
+      userId: req.user.id
+    });
+    
+    throw error;
+  }
+});
+```
+
+### Pattern 4: Custom Notifications
+
+```javascript
+app.post('/critical-action', async (req, res) => {
+  // Perform critical action
+  await performCriticalAction();
+  
+  // Send notification
+  await monitor.notify('critical', 
+    'Critical Action Performed',
+    'A critical action was just performed',
+    {
+      user: req.user.email,
+      action: 'critical-action',
+      timestamp: new Date().toISOString()
+    }
+  );
+  
+  res.json({ success: true });
+});
+```
+
+## Monitoring Dashboard
+
+Access monitoring data via endpoints:
+
+```javascript
+// Get current status
+app.get('/admin/monitor', (req, res) => {
+  const status = monitor.getStatus();
+  res.json(status);
+});
+
+// Get system info
+app.get('/admin/system', (req, res) => {
+  const info = monitor.getSystemInfo();
+  res.json(info);
+});
+
+// Get metrics history
+app.get('/admin/metrics', (req, res) => {
+  const metrics = monitor.getMetricsHistory();
+  res.json(metrics);
+});
+```
+
+## Troubleshooting
+
+### Logs not appearing?
+
+Check that the logs directory exists and is writable:
+```bash
+mkdir -p logs
+chmod 755 logs
+```
+
+### Emails not sending?
+
+1. Check your SMTP credentials
+2. Verify firewall allows outbound connections on port 587
+3. Check spam folder
+4. Look at error logs: `cat logs/error-*.log`
+
+### High CPU alerts?
+
+This is normal during startup. If it persists:
+1. Increase the threshold
+2. Increase the consecutive failures count
+3. Check your application for performance issues
+
+## Best Practices
+
+1. **Start Simple**: Begin with basic error tracking, add features gradually
+2. **Test Notifications**: Send test alerts before going to production
+3. **Adjust Thresholds**: Fine-tune based on your app's normal behavior
+4. **Use Environment Variables**: Keep credentials out of code
+5. **Monitor the Monitor**: Check logs to ensure monitoring is working
+6. **Set Appropriate Cooldowns**: Prevent alert fatigue
+
+## Need Help?
+
+- 📖 **Full Documentation**: See `README.md`
+- 🔧 **Setup Guide**: See `SETUP_GUIDE.md`
+- ⚡ **Quick Reference**: See `QUICK_REFERENCE.md`
+- 🏗️ **Architecture**: See `ARCHITECTURE.md`
+- 💡 **Examples**: Check `examples/express-app.js`
+
+## What's Next?
+
+- Explore all configuration options
+- Set up production deployment
+- Add custom health checks
+- Integrate with your CI/CD pipeline
+- Create custom dashboards
+
+Happy monitoring! 🎉
+