@bitcall/pm2-pulse-agent 1.0.1-beta.0 → 1.0.1-beta.2

package/README.md

@@ -1 +1,176 @@
-# MONITORING-SERVICE
+# PM2 Pulse Agent
+
+A Node.js monitoring agent that tracks server metrics (CPU, RAM, processes) and sends real-time alerts to a gRPC monitoring service.
+
+## Features
+
+- **Real-time Metrics Collection**: Monitors CPU usage, RAM consumption, and PM2 process states
+- **Configurable Thresholds**: Set custom CPU and RAM alert thresholds
+- **PM2 Integration**: Tracks all PM2-managed processes and their status
+- **gRPC Communication**: Sends metrics to a monitoring server via gRPC
+- **Authentication Support**: Optional Bearer token authentication
+- **Singleton Pattern**: Ensures only one agent instance runs per server
+
+## Installation
+
+```bash
+npm install @bitcall/pm2-pulse-agent@beta
+```
+
+### Dependencies
+
+- `@grpc/grpc-js` - gRPC protocol implementation
+- `@grpc/proto-loader` - Protocol buffer loader
+- `dotenv` - Environment variable management
+
+## Setup
+
+Run the interactive setup script to configure the agent:
+
+```bash
+npx @bitcall/pm2-pulse-agent pm2-pulse-setup
+```
+
+Or if installed globally:
+
+```bash
+npm install -g @bitcall/pm2-pulse-agent@beta
+pm2-pulse-setup
+```
+
+This will prompt you to configure:
+- **AUTH_TOKEN**: Secret token for server authentication (optional)
+- **MONITOR_SERVER**: gRPC server address (default: `localhost:50051`)
+- **VPS_ID**: Unique identifier for this server (default: `server-{hostname}`)
+
+Settings are saved to `.env` file in your current directory.
+
+## Usage
+
+### Start the Agent
+
+**Using npx (recommended):**
+```bash
+npx @bitcall/pm2-pulse-agent pm2-pulse-agent
+```
+
+**If installed globally:**
+```bash
+pm2-pulse-agent
+```
+
+**Run with PM2 (for persistent monitoring):**
+```bash
+pm2 start "npx @bitcall/pm2-pulse-agent pm2-pulse-agent" --name pm2-pulse-agent
+```
+
+### Configuration Options
+
+Environment variables in `.env`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MONITOR_SERVER` | `localhost:50051` | gRPC server host:port |
+| `VPS_ID` | `server-{hostname}` | Unique server identifier |
+| `AUTH_TOKEN` | `` | Bearer token for authentication |
+| `CPU_THRESHOLD` | `70` | CPU alert threshold (%) |
+| `RAM_THRESHOLD` | `80` | RAM alert threshold (%) |
+
+## How It Works
+
+1. **Agent Startup**: Initializes gRPC client and logs configuration
+2. **Metrics Collection**: Every 10 seconds, collects:
+   - CPU usage (2-second measurement window)
+   - RAM usage and statistics
+   - PM2 process information (name, status, restarts, CPU, memory)
+3. **Alert Detection**: Triggers alerts when:
+   - CPU exceeds threshold
+   - RAM exceeds threshold
+   - Any process is not in "online" status
+4. **Data Transmission**: Sends metrics to gRPC server with optional authentication
+5. **Logging**: Displays metrics and alerts in console
+
+## Metrics Structure
+
+```javascript
+{
+  vps_id: string,           // Server identifier
+  cpu: number,              // CPU usage percentage (0-100)
+  ram: number,              // RAM usage percentage (0-100)
+  ram_used_mb: number,      // Used RAM in MB
+  ram_total_mb: number,     // Total RAM in MB
+  processes: [              // PM2 processes
+    {
+      name: string,
+      status: string,       // 'online', 'stopped', etc.
+      restarts: number,
+      cpu_percent: number,
+      memory_mb: number
+    }
+  ],
+  alerts: string[],         // Alert messages
+  urgent: boolean,          // Whether message contains alerts
+  timestamp: number         // Unix timestamp
+}
+```
+
+## Example Output
+
+```
+============================================================
+🚀 PM2 Monitoring Agent Started
+============================================================
+VPS ID: server-app-01
+Server: monitoring-server.example.com:50051
+Authentication: ✓ Enabled
+Check interval: 10 second(s)
+CPU Threshold: 70%
+RAM Threshold: 80%
+============================================================
+
+[14:23:45] CPU: 45% | RAM: 2048/8192MB (25%) | Alerts: 0
+[14:23:55] CPU: 62% | RAM: 3512/8192MB (43%) | Alerts: 0
+[14:24:05] CPU: 85% | RAM: 6144/8192MB (75%) | Alerts: 1 🚨
+✓ Alert sent to server
+```
+
+## Quick Start Guide
+
+1. **Install the package:**
+   ```bash
+   npm install -g @bitcall/pm2-pulse-agent@beta
+   ```
+
+2. **Run setup:**
+   ```bash
+   pm2-pulse-setup
+   ```
+
+3. **Start monitoring:**
+   ```bash
+   pm2 start pm2-pulse-agent --name monitoring-agent
+   ```
+
+4. **Check status:**
+   ```bash
+   pm2 logs monitoring-agent
+   ```
+
+## Troubleshooting
+
+**Agent not connecting to server:**
+- Verify `MONITOR_SERVER` address is correct in `.env`
+- Check network connectivity: `telnet <server-host> <port>`
+- Ensure firewall allows outbound connections
+
+**PM2 processes not detected:**
+- Verify PM2 is installed: `pm2 --version`
+- Check PM2 has running processes: `pm2 list`
+
+**Authentication errors:**
+- Verify `AUTH_TOKEN` in `.env` matches server configuration
+- Check token hasn't expired
+
+## License
+
+MIT

package/agent.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 const os = require('os')
 const { exec } = require('child_process')
 const grpc = require('@grpc/grpc-js')

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@bitcall/pm2-pulse-agent",
-  "version": "1.0.1-beta.0",
+  "version": "1.0.1-beta.2",
+  "bin": {
+    "pm2-pulse-setup": "./scripts/setup-agent.js",
+    "pm2-pulse-agent": "./agent.js"
+  },
   "scripts": {
     "agent": "node agent.js",
     "monitor": "node agent.js",

package/scripts/setup-agent.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 const fs = require('fs')
 const path = require('path')
 const readline = require('readline')