📊 @thaparoyal/sys-monitor

A professional, real-time system monitoring package for Node.js with beautiful CLI visualization, REST API, WebSocket streaming, and comprehensive metrics collection. Perfect for monitoring servers, development environments, and production systems.

✨ Features

🔍 Comprehensive System Metrics

• CPU Monitoring: Per-core usage, total utilization, load averages
• Memory Analysis: RAM usage, swap statistics, memory pressure
• Disk Monitoring: Usage per mount point, I/O statistics
• Network Tracking: Interface statistics, active connections
• Process Management: Top resource-consuming processes, process count

🖥️ Multiple Interface Options

• Beautiful CLI: Real-time terminal visualization with progress bars
• REST API: HTTP endpoints for metrics retrieval
• WebSocket Streaming: Real-time data streaming for web applications
• Programmatic API: Direct integration in Node.js applications

🎨 Professional Visualization

• Stable Terminal Display: No flickering or shifting issues
• Color-coded Metrics: Visual indicators for system health
• Progress Bars: Intuitive representation of usage percentages
• Responsive Design: Adapts to different terminal sizes

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g @thaparoyal/sys-monitor

# Local installation
npm install @thaparoyal/sys-monitor

Basic Usage

# Start with default settings
sys-monitor

# Console-only mode with terminal visualization
sys-monitor --console

# Custom port and authentication
sys-monitor --port 8080 --token my-secret-token

# Custom update interval (2 seconds)
sys-monitor --console --interval 2000

📖 Detailed Usage

CLI Options

| Option | Alias | Type | Default | Description | |--------|-------|------|---------|-------------| | --port | -p | number | 3000 | Port for REST API and WebSocket | | --token | -t | string | - | Authentication token | | --interval | -i | number | 1000 | Update interval in milliseconds | | --console | -c | boolean | false | Enable terminal-only mode | | --help | -h | - | - | Show help information |

Examples

# Development mode with fast updates
sys-monitor --console --interval 500

# Production server with authentication
sys-monitor --port 8080 --token production-secret --interval 5000

# Web interface access
sys-monitor --port 3000
# Then visit: http://localhost:3000

🔌 API Reference

REST API Endpoints

Get System Metrics

GET /stats
Authorization: Bearer <your-token>

Response:

{
  "cpu": {
    "perCore": [
      {
        "user": 123456,
        "nice": 0,
        "sys": 23456,
        "idle": 1234567
      }
    ],
    "loadAvg": [0.5, 0.3, 0.2]
  },
  "memory": {
    "total": 8589934592,
    "used": 4294967296,
    "free": 4294967296
  },
  "disk": [
    {
      "mount": "/",
      "used": 10737418240,
      "free": 21474836480
    }
  ],
  "network": {
    "interfaces": {
      "eth0": [
        {
          "address": "192.168.1.100",
          "family": "IPv4"
        }
      ]
    }
  },
  "processCount": 125,
  "topProcesses": [
    {
      "pid": 1234,
      "comm": "node",
      "cpu": 15.5,
      "mem": 2.3
    }
  ]
}

Get Process Information

GET /processes
Authorization: Bearer <your-token>

WebSocket API

Connect to ws://localhost:3001 for real-time metrics streaming.

const WebSocket = require('ws');

const ws = new WebSocket('ws://localhost:3001', 'your-token');

ws.on('message', (data) => {
  const metrics = JSON.parse(data);
  console.log('CPU Usage:', metrics.cpu);
  console.log('Memory Usage:', metrics.memory);
});

Programmatic Usage

const monitor = require('@thaparoyal/sys-monitor');

// Start monitoring server
monitor.start({
  port: 3000,
  token: 'your-secret-token',
  interval: 1000,
  printConsole: false
});

// Access metrics directly
const { metrics } = require('@thaparoyal/sys-monitor');

const cpuUsage = metrics.cpu.getCpuUsage();
const memoryUsage = metrics.memory.getMemoryUsage();
const diskUsage = metrics.disk.getDiskUsage();
const networkStats = metrics.network.getNetworkStats();
const processCount = metrics.processes.getProcessCount();
const topProcesses = metrics.processes.getTopProcesses();

🌐 Web Interface

When running the server, access the web interface at http://localhost:3000 for a beautiful, real-time monitoring dashboard.

Features:

• Real-time updates via WebSocket
• Responsive design
• Dark theme
• Interactive progress bars
• Automatic reconnection

🛠️ Development

Prerequisites

• Node.js >= 18
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd sys-monitor

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

Available Scripts

| Script | Description | |--------|-------------| | npm run build | Build TypeScript to JavaScript | | npm run start | Start the application | | npm run dev | Development mode with auto-restart | | npm test | Run test suite | | npm run lint | Run ESLint | | npm run format | Format code with Prettier |

Project Structure

src/
├── api/           # REST API server
├── auth/          # Authentication utilities
├── metrics/       # System metrics collection
├── types/         # TypeScript type definitions
├── visualization/ # Terminal visualization
├── ws/           # WebSocket server
├── cli.ts        # CLI entry point
└── index.ts      # Main module exports

📊 Metrics Details

CPU Metrics

• Per-core usage: Individual CPU core utilization
• Load average: 1, 5, and 15-minute averages
• Usage calculation: (user + nice + sys) / total * 100

Memory Metrics

• Total RAM: Total available memory
• Used memory: Currently allocated memory
• Free memory: Available memory
• Usage percentage: Used / Total * 100

Disk Metrics

• Mount points: All mounted filesystems
• Used space: Space occupied by files
• Free space: Available space
• Usage percentage: Used / (Used + Free) * 100

Network Metrics

• Interfaces: All network interfaces
• IP addresses: IPv4 and IPv6 addresses
• Active connections: TCP/UDP connections (when available)

Process Metrics

• Top processes: Highest CPU/memory consumers
• Process count: Total running processes
• Resource usage: CPU and memory percentages

🔧 Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | Server port | 3000 | | TOKEN | Authentication token | - | | INTERVAL | Update interval (ms) | 1000 |

Authentication

When a token is provided, all API endpoints and WebSocket connections require authentication:

# REST API
curl -H "Authorization: Bearer your-token" http://localhost:3000/stats

# WebSocket
const ws = new WebSocket('ws://localhost:3001', 'your-token');

🐛 Troubleshooting

Common Issues

Q: Terminal display is flickering or shifting A: This has been fixed in the latest version. Ensure you're using the latest release.

Q: Network connection errors A: The package gracefully handles missing network tools. No action needed.

Q: Permission denied errors A: Some metrics require elevated privileges. Run with appropriate permissions.

Q: Port already in use A: Use a different port with --port option.

Performance Considerations

• Update interval: Lower intervals (500ms) provide more real-time data but use more CPU
• Process monitoring: Top processes calculation can be CPU-intensive
• Network connections: May not be available on all systems

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run linting and tests
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with TypeScript for type safety
• Uses cli-table3 for beautiful terminal tables
• Powered by Node.js system APIs
• Inspired by tools like htop and iotop

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Email: [email protected]

Made with ❤️ by thaparoyal