@gazzehamine/armada-watch-agent 1.0.0

package/.env.example

@@ -0,0 +1,10 @@
+# Agent Configuration
+SERVER_URL=http://your-monitoring-server:4000
+INSTANCE_NAME=My EC2 Instance
+REGION=us-east-1
+
+# Collection interval in seconds
+COLLECTION_INTERVAL=10
+
+# Optional: Set custom instance ID (defaults to hostname)
+# INSTANCE_ID=i-1234567890abcdef0

package/README.md

@@ -0,0 +1,138 @@
+# Armada Watch Agent
+
+Lightweight monitoring agent for EC2 instances. Collects and sends system metrics to your Armada Watch monitoring server.
+
+## Installation
+
+### Via NPM (Recommended)
+
+```bash
+npm install -g @gazzehamine/armada-watch-agent
+```
+
+## Quick Start
+
+### 1. Set Environment Variables
+
+Create a `.env` file:
+
+```bash
+SERVER_URL=http://your-monitoring-server:4000
+INSTANCE_NAME=Production Web Server
+REGION=us-east-1
+COLLECTION_INTERVAL=10
+```
+
+Or set them directly:
+
+```bash
+export SERVER_URL=http://your-monitoring-server:4000
+export INSTANCE_NAME="Production Web Server"
+export REGION=us-east-1
+export COLLECTION_INTERVAL=10
+```
+
+### 2. Run the Agent
+
+```bash
+# If installed via npm
+armada-watch-agent
+
+# Or with npx
+npx @gazzehamine/armada-watch-agent
+
+# If built from source
+npm start
+```
+
+### 3. Run as a Service (Production)
+
+**Using PM2:**
+
+```bash
+npm install -g pm2
+pm2 start armada-watch-agent --name armada-watch
+pm2 save
+pm2 startup
+```
+
+**Using systemd:**
+
+```bash
+sudo tee /etc/systemd/system/armada-watch.service > /dev/null <<EOF
+[Unit]
+Description=Armada Watch Monitoring Agent
+After=network.target
+
+[Service]
+Type=simple
+User=$USER
+WorkingDirectory=$HOME
+Environment="SERVER_URL=http://your-server:4000"
+Environment="INSTANCE_NAME=My Instance"
+Environment="REGION=us-east-1"
+ExecStart=$(which armada-watch-agent)
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable armada-watch
+sudo systemctl start armada-watch
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SERVER_URL` | Yes | - | URL of your monitoring server |
+| `INSTANCE_NAME` | No | hostname | Friendly name for this instance |
+| `REGION` | No | `unknown` | AWS region (e.g., us-east-1) |
+| `INSTANCE_ID` | No | hostname | EC2 instance ID (auto-detected on EC2) |
+| `COLLECTION_INTERVAL` | No | `10` | Interval in seconds between metric collections |
+
+## Collected Metrics
+
+The agent collects:
+
+- **CPU Usage** - Overall CPU utilization percentage
+- **Memory Usage** - RAM usage percentage and amounts
+- **Disk Usage** - Disk space utilization
+- **Network Traffic** - Network RX/TX bytes
+- **System Info** - Platform, architecture, CPU model
+- **Top Processes** - Top 10 processes by CPU/Memory
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Network access to monitoring server on port 4000
+
+## Troubleshooting
+
+### Agent can't connect to server
+
+```bash
+# Test connectivity
+curl http://your-server:4000/health
+
+# Check agent logs (PM2)
+pm2 logs armada-watch
+
+# Check agent logs (systemd)
+sudo journalctl -u armada-watch -f
+```
+
+### Permission errors
+
+The agent needs permission to read system metrics. Run with appropriate user permissions.
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/gazzehamine/armada-watch

package/dist/collector.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSystemInfo = getSystemInfo;
+exports.collectMetrics = collectMetrics;
+exports.collectProcesses = collectProcesses;
+const systeminformation_1 = __importDefault(require("systeminformation"));
+const os_1 = __importDefault(require("os"));
+let lastNetworkStats = null;
+async function getSystemInfo() {
+    const cpu = await systeminformation_1.default.cpu();
+    return {
+        platform: os_1.default.platform(),
+        arch: os_1.default.arch(),
+        hostname: os_1.default.hostname(),
+        cpuModel: cpu.manufacturer + " " + cpu.brand,
+        cpuCores: cpu.cores,
+    };
+}
+async function collectMetrics() {
+    // CPU Usage
+    const cpuLoad = await systeminformation_1.default.currentLoad();
+    const cpuUsage = cpuLoad.currentLoad;
+    // Memory Usage
+    const mem = await systeminformation_1.default.mem();
+    const memoryUsage = (mem.used / mem.total) * 100;
+    const memoryTotal = mem.total;
+    const memoryUsed = mem.used;
+    // Disk Usage
+    const fsSize = await systeminformation_1.default.fsSize();
+    const mainDisk = fsSize[0];
+    const diskUsage = mainDisk ? (mainDisk.used / mainDisk.size) * 100 : 0;
+    const diskTotal = mainDisk ? mainDisk.size : 0;
+    const diskUsed = mainDisk ? mainDisk.used : 0;
+    // Network Usage (calculate rate per second)
+    const networkStats = await systeminformation_1.default.networkStats();
+    const mainInterface = networkStats[0];
+    let networkRx = 0;
+    let networkTx = 0;
+    if (mainInterface && lastNetworkStats) {
+        const timeDiff = (Date.now() - lastNetworkStats.timestamp) / 1000; // seconds
+        networkRx = (mainInterface.rx_bytes - lastNetworkStats.rx) / timeDiff;
+        networkTx = (mainInterface.tx_bytes - lastNetworkStats.tx) / timeDiff;
+    }
+    if (mainInterface) {
+        lastNetworkStats = {
+            rx: mainInterface.rx_bytes,
+            tx: mainInterface.tx_bytes,
+            timestamp: Date.now(),
+        };
+    }
+    // Uptime
+    const uptime = os_1.default.uptime();
+    return {
+        cpuUsage,
+        memoryUsage,
+        memoryTotal,
+        memoryUsed,
+        diskUsage,
+        diskTotal,
+        diskUsed,
+        networkRx,
+        networkTx,
+        uptime,
+    };
+}
+async function collectProcesses() {
+    const processes = await systeminformation_1.default.processes();
+    return processes.list
+        .filter((p) => p.cpu > 0 || p.mem > 0)
+        .sort((a, b) => b.cpu - a.cpu)
+        .slice(0, 20)
+        .map((p) => ({
+        pid: p.pid,
+        name: p.name,
+        cpu: p.cpu,
+        memory: p.mem,
+    }));
+}

package/dist/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv_1 = __importDefault(require("dotenv"));
+const axios_1 = __importDefault(require("axios"));
+const os_1 = __importDefault(require("os"));
+const collector_1 = require("./collector");
+// Load environment variables
+dotenv_1.default.config();
+const SERVER_URL = process.env.SERVER_URL || "http://localhost:4000";
+const INSTANCE_NAME = process.env.INSTANCE_NAME || os_1.default.hostname();
+const REGION = process.env.REGION || "unknown";
+const INSTANCE_ID = process.env.INSTANCE_ID || os_1.default.hostname();
+const COLLECTION_INTERVAL = parseInt(process.env.COLLECTION_INTERVAL || "10") * 1000;
+let instanceInfo = null;
+async function initializeAgent() {
+    try {
+        console.log("🔄 Initializing Armada Watch Agent...");
+        console.log(`📡 Server: ${SERVER_URL}`);
+        console.log(`🖥️  Instance: ${INSTANCE_NAME}`);
+        console.log(`🌍 Region: ${REGION}`);
+        // Get system info once at startup
+        const sysInfo = await (0, collector_1.getSystemInfo)();
+        instanceInfo = {
+            instanceId: INSTANCE_ID,
+            name: INSTANCE_NAME,
+            privateIp: getLocalIpAddress(),
+            publicIp: await getPublicIpAddress(),
+            region: REGION,
+            platform: sysInfo.platform,
+            arch: sysInfo.arch,
+            hostname: sysInfo.hostname,
+            cpuModel: sysInfo.cpuModel,
+            cpuCores: sysInfo.cpuCores,
+        };
+        console.log("✅ Agent initialized successfully");
+        console.log(`🔁 Collection interval: ${COLLECTION_INTERVAL / 1000}s`);
+    }
+    catch (error) {
+        console.error("❌ Failed to initialize agent:", error);
+        process.exit(1);
+    }
+}
+async function sendMetrics() {
+    try {
+        const metrics = await (0, collector_1.collectMetrics)();
+        const processes = await (0, collector_1.collectProcesses)();
+        const payload = {
+            instanceInfo,
+            metrics: {
+                instanceId: INSTANCE_ID,
+                ...metrics,
+            },
+            processes,
+        };
+        await axios_1.default.post(`${SERVER_URL}/api/metrics`, payload, {
+            timeout: 5000,
+        });
+        console.log(`✓ Metrics sent successfully - CPU: ${metrics.cpuUsage.toFixed(1)}% | Memory: ${metrics.memoryUsage.toFixed(1)}%`);
+    }
+    catch (error) {
+        if (axios_1.default.isAxiosError(error)) {
+            console.error(`✗ Failed to send metrics: ${error.message}`);
+        }
+        else {
+            console.error("✗ Failed to collect metrics:", error);
+        }
+    }
+}
+function getLocalIpAddress() {
+    const networkInterfaces = os_1.default.networkInterfaces();
+    for (const name of Object.keys(networkInterfaces)) {
+        const interfaces = networkInterfaces[name];
+        if (!interfaces)
+            continue;
+        for (const iface of interfaces) {
+            // Skip internal and non-IPv4 addresses
+            if (iface.family === "IPv4" && !iface.internal) {
+                return iface.address;
+            }
+        }
+    }
+    return "127.0.0.1";
+}
+async function getPublicIpAddress() {
+    try {
+        // Try AWS metadata service first (for EC2 instances)
+        const response = await axios_1.default.get("http://169.254.169.254/latest/meta-data/public-ipv4", {
+            timeout: 1000,
+        });
+        return response.data;
+    }
+    catch {
+        // If not on AWS or no public IP, return undefined
+        return undefined;
+    }
+}
+async function main() {
+    await initializeAgent();
+    // Send metrics immediately
+    await sendMetrics();
+    // Set up periodic collection
+    setInterval(sendMetrics, COLLECTION_INTERVAL);
+    // Handle graceful shutdown
+    process.on("SIGINT", () => {
+        console.log("\n👋 Shutting down agent...");
+        process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+        console.log("\n👋 Shutting down agent...");
+        process.exit(0);
+    });
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@gazzehamine/armada-watch-agent",
+  "version": "1.0.0",
+  "description": "Monitoring agent for Armada Watch - EC2 instance monitoring",
+  "main": "dist/index.js",
+  "bin": {
+    "armada-watch-agent": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node-dev --respawn src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "monitoring",
+    "ec2",
+    "aws",
+    "metrics",
+    "devops",
+    "observability"
+  ],
+  "author": "Gazzeh Amine",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gazzehamine/armada-watch.git",
+    "directory": "agent"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^16.3.1",
+    "systeminformation": "^5.21.20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.10",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}