docs: add comprehensive README with shields and LICENSE
- Add README with shields.io badges for Go, SvelteKit, Docker - Document quick start with Docker Compose - Add multi-host monitoring setup guide with network diagram - Include full API reference with endpoint table - Add configuration section with environment variables - Document keyboard shortcuts and alert configuration - Add troubleshooting section with collapsible details - Include MIT LICENSE file 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024 System Monitor Contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
393
README.md
Normal file
393
README.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# System Monitor
|
||||
|
||||
<div align="center">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**A real-time Linux system monitoring dashboard with a modern web interface**
|
||||
|
||||
[Features](#features) • [Quick Start](#quick-start) • [Multi-Host Setup](#multi-host-monitoring) • [API](#api-reference) • [Development](#development)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
System Monitor is a lightweight, containerized monitoring solution that provides real-time visibility into your Linux systems. Built with a Go backend for efficient metric collection and a SvelteKit frontend for a responsive, modern UI.
|
||||
|
||||
### Key Highlights
|
||||
|
||||
- **Real-time streaming** via Server-Sent Events (SSE)
|
||||
- **Zero dependencies** on the host system (runs in Docker)
|
||||
- **Multi-host support** for monitoring multiple machines from one dashboard
|
||||
- **Desktop notifications** for critical alerts
|
||||
- **Process management** with kill/pause/resume functionality
|
||||
- **Dark/Light themes** with responsive mobile design
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
| Category | Features |
|
||||
|----------|----------|
|
||||
| **System** | Hostname, kernel version, uptime, architecture |
|
||||
| **CPU** | Per-core usage, frequency, load averages |
|
||||
| **Memory** | RAM usage, buffers, cache, swap |
|
||||
| **Disk** | Mount points, usage, I/O rates |
|
||||
| **Network** | Interface stats, bandwidth rates, TCP connections |
|
||||
| **Processes** | Top by CPU/Memory, detailed view, signal control |
|
||||
| **Temperature** | Hardware sensors via hwmon |
|
||||
| **GPU** | AMD GPU monitoring (utilization, VRAM, power, clocks) |
|
||||
| **Docker** | Container stats (CPU, memory, status) |
|
||||
| **Systemd** | Service status monitoring |
|
||||
| **Alerts** | Configurable thresholds with desktop notifications |
|
||||
| **History** | Sparkline charts for CPU, memory, network, disk I/O |
|
||||
| **Export** | CSV and JSON export of current metrics |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Using Docker Compose (Recommended)
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/system-monitor.git
|
||||
cd system-monitor
|
||||
|
||||
# Start the containers
|
||||
docker compose up -d
|
||||
|
||||
# Access the dashboard
|
||||
open http://localhost:9847
|
||||
```
|
||||
|
||||
### Ports
|
||||
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| Frontend | 9847 | Web dashboard |
|
||||
| Backend | 9848 | API server (internal) |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The backend container supports the following environment variables:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PORT` | `8080` | Backend server port |
|
||||
| `PROC_PATH` | `/proc` | Path to proc filesystem |
|
||||
| `SYS_PATH` | `/sys` | Path to sys filesystem |
|
||||
| `MTAB_PATH` | `/etc/mtab` | Path to mount table |
|
||||
| `DOCKER_SOCKET` | `/var/run/docker.sock` | Docker socket path |
|
||||
| `DEFAULT_REFRESH_INTERVAL` | `5s` | Default metric collection interval |
|
||||
|
||||
### Required Volume Mounts
|
||||
|
||||
For the backend to collect host metrics, these mounts are required:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /proc:/host/proc:ro # Process information
|
||||
- /sys:/host/sys:ro # Hardware sensors, GPU info
|
||||
- /etc/mtab:/host/etc/mtab:ro # Disk mount information
|
||||
```
|
||||
|
||||
### Optional Features
|
||||
|
||||
<details>
|
||||
<summary><b>Docker Monitoring</b></summary>
|
||||
|
||||
Mount the Docker socket to enable container monitoring:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Systemd Service Monitoring</b></summary>
|
||||
|
||||
Mount the D-Bus socket to enable systemd service monitoring:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Multi-Host Monitoring
|
||||
|
||||
System Monitor supports monitoring multiple hosts from a single dashboard. Each host runs its own backend container, and the frontend can switch between them.
|
||||
|
||||
### Setting Up Remote Hosts
|
||||
|
||||
1. **Deploy on each host** you want to monitor:
|
||||
|
||||
```bash
|
||||
# On remote-host-1 (e.g., 192.168.1.100)
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
2. **Configure CORS** (if accessing from a different origin):
|
||||
|
||||
The backend allows cross-origin requests by default. Ensure ports are accessible.
|
||||
|
||||
3. **Add hosts in the dashboard**:
|
||||
- Click the **host selector** dropdown in the header
|
||||
- Click **"Add Remote Host"**
|
||||
- Enter a name (e.g., "Web Server") and URL (e.g., `http://192.168.1.100:9847`)
|
||||
|
||||
### Network Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Your Browser │
|
||||
│ http://localhost:9847 │
|
||||
└──────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────┐ ┌────────────┐ ┌────────────┐
|
||||
│ Host A │ │ Host B │ │ Host C │
|
||||
│ (local) │ │ :9847 │ │ :9847 │
|
||||
│ Frontend + │ │ Frontend + │ │ Frontend + │
|
||||
│ Backend │ │ Backend │ │ Backend │
|
||||
└────────────┘ └────────────┘ └────────────┘
|
||||
```
|
||||
|
||||
### Host Configuration Storage
|
||||
|
||||
Host configurations are stored in browser localStorage under the key `system-monitor-hosts`. The active host is stored in `system-monitor-active-host`.
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/v1/stream` | SSE stream of real-time metrics |
|
||||
| `GET` | `/api/v1/history` | Historical metric data (1 hour) |
|
||||
| `GET` | `/api/v1/alerts` | Current alerts and configuration |
|
||||
| `POST` | `/api/v1/alerts/config` | Update alert thresholds |
|
||||
| `POST` | `/api/v1/alerts/:id/acknowledge` | Acknowledge an alert |
|
||||
| `GET` | `/api/v1/processes/:pid` | Detailed process information |
|
||||
| `POST` | `/api/v1/processes/:pid/signal` | Send signal to process |
|
||||
| `POST` | `/api/v1/settings/refresh` | Update refresh interval |
|
||||
| `GET` | `/api/v1/export/metrics?format=csv\|json` | Export current metrics |
|
||||
| `GET` | `/health` | Health check endpoint |
|
||||
|
||||
### SSE Stream Format
|
||||
|
||||
The `/api/v1/stream` endpoint sends JSON messages with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"system": { "hostname": "...", "kernel": "...", "uptime": 12345 },
|
||||
"cpu": { "cores": [...], "totalUsage": 15.5, "loadAverage": {...} },
|
||||
"memory": { "total": 16000000000, "used": 8000000000, ... },
|
||||
"disk": { "mounts": [...], "io": [...] },
|
||||
"network": { "interfaces": [...], "connectionCount": 42 },
|
||||
"processes": { "topByCpu": [...], "topByMemory": [...], "total": 200 },
|
||||
"temperature": { "sensors": [...] },
|
||||
"gpu": { "available": true, "utilization": 45, ... },
|
||||
"docker": { "available": true, "containers": [...] },
|
||||
"systemd": { "available": true, "services": [...] }
|
||||
}
|
||||
```
|
||||
|
||||
### Process Signal API
|
||||
|
||||
```bash
|
||||
# Send SIGTERM (graceful termination)
|
||||
curl -X POST http://localhost:9847/api/v1/processes/1234/signal \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"signal": 15}'
|
||||
|
||||
# Send SIGKILL (force kill)
|
||||
curl -X POST http://localhost:9847/api/v1/processes/1234/signal \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"signal": 9}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Go 1.23+**
|
||||
- **Node.js 22+**
|
||||
- **Docker & Docker Compose** (for containerized development)
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Backend (Go)
|
||||
cd backend
|
||||
go mod download
|
||||
go run ./cmd/server
|
||||
|
||||
# Frontend (SvelteKit)
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Backend tests
|
||||
cd backend
|
||||
go test ./...
|
||||
|
||||
# Frontend tests
|
||||
cd frontend
|
||||
npm test
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
system-monitor/
|
||||
├── backend/
|
||||
│ ├── cmd/server/ # Main entry point
|
||||
│ ├── internal/
|
||||
│ │ ├── api/ # HTTP handlers and routes
|
||||
│ │ ├── alerts/ # Alert management
|
||||
│ │ ├── collectors/ # Metric collectors
|
||||
│ │ ├── config/ # Configuration
|
||||
│ │ ├── history/ # Historical data storage
|
||||
│ │ ├── models/ # Data structures
|
||||
│ │ └── sse/ # Server-Sent Events broker
|
||||
│ └── Dockerfile
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── lib/
|
||||
│ │ │ ├── api/ # API clients
|
||||
│ │ │ ├── components/ # Svelte components
|
||||
│ │ │ ├── stores/ # Svelte stores
|
||||
│ │ │ ├── types/ # TypeScript types
|
||||
│ │ │ └── utils/ # Utility functions
|
||||
│ │ └── routes/ # SvelteKit routes
|
||||
│ └── Dockerfile
|
||||
└── docker-compose.yaml
|
||||
```
|
||||
|
||||
### Building Docker Images
|
||||
|
||||
```bash
|
||||
# Build both images
|
||||
docker compose build
|
||||
|
||||
# Build specific service
|
||||
docker compose build backend
|
||||
docker compose build frontend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `T` | Toggle dark/light theme |
|
||||
| `R` | Cycle refresh rate |
|
||||
| `?` | Show keyboard shortcuts |
|
||||
| `Esc` | Close modals/panels |
|
||||
|
||||
---
|
||||
|
||||
## Alerts & Notifications
|
||||
|
||||
### Configuring Thresholds
|
||||
|
||||
1. Open the **Alerts** card
|
||||
2. Click **"Configure Thresholds"**
|
||||
3. Set warning and critical percentages for each metric type
|
||||
4. Click **"Save Configuration"**
|
||||
|
||||
### Desktop Notifications
|
||||
|
||||
1. Enable the **"Desktop Notifications"** toggle in the Alerts card
|
||||
2. Allow browser notification permission when prompted
|
||||
3. Notifications will appear for new warning/critical alerts
|
||||
|
||||
> **Note:** Critical alerts require manual dismissal; warnings auto-close after 10 seconds.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<details>
|
||||
<summary><b>No metrics displayed</b></summary>
|
||||
|
||||
1. Check if backend is running: `docker compose ps`
|
||||
2. Verify volume mounts: `docker inspect sysmon-backend`
|
||||
3. Check backend logs: `docker compose logs backend`
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>GPU not detected</b></summary>
|
||||
|
||||
AMD GPU monitoring requires:
|
||||
- AMD GPU with amdgpu driver
|
||||
- `/sys/class/drm/card*/device/` accessible
|
||||
- Proper volume mount: `-v /sys:/host/sys:ro`
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Docker containers not showing</b></summary>
|
||||
|
||||
Ensure Docker socket is mounted:
|
||||
```yaml
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Systemd services not showing</b></summary>
|
||||
|
||||
Mount D-Bus socket and ensure the container can access it:
|
||||
```yaml
|
||||
volumes:
|
||||
- /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**[Back to top](#system-monitor)**
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user