ducky/nerd-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat: implement real-time updates and enhance monitoring system

Browse Source 
- Add structured logging with slog throughout application
- Implement real-time updates using Server-Sent Events and HTMX
- Add broadcaster system for instant UI updates when agents report stats
- Replace meta refresh with HTMX-powered seamless updates
- Add new API endpoints for HTMX fragments and SSE events
- Update templates to use HTMX for instant data refresh
- Enhance README with real-time features and updated documentation
- Remove obsolete template generation file
This commit is contained in:
Ducky SSH User
2025-12-20 08:08:56 +00:00
parent 50dcfcdc83
commit 8cb33dbc90
8 changed files with 437 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@@ -1,22 +1,25 @@
# Nerd Monitor 📊
A lightweight, cross-platform system monitoring solution written in Go. Monitor CPU, memory, and disk usage across multiple machines with a beautiful web dashboard.
A lightweight, cross-platform system monitoring solution written in Go. Monitor CPU, memory, and disk usage across multiple machines with a beautiful web dashboard featuring instant real-time updates powered by Server-Sent Events and HTMX.
![Go](https://img.shields.io/badge/Go-1.23-blue?logo=go)
![Real-time](https://img.shields.io/badge/real--time-SSE%20%2B%20HTMX-orange?logo=lightning)
![License](https://img.shields.io/badge/license-MIT-green)
![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-important)
## Features
- 🖥️ **Multi-platform Support** - Deploy agents on Linux, macOS, and Windows (AMD64 & ARM64)
- 📈 **Real-time Monitoring** - Track CPU, RAM, and Disk usage with 15-second refresh intervals
- ⚡ **Instant Real-time Updates** - Stats update immediately when agents report, not on fixed intervals
- 🟢 **Live Status Indicators** - See which machines are online/offline at a glance
- 🔒 **Secure Authentication** - Session-based admin authentication for the dashboard
- 🧹 **Stale Agent Management** - Automatically detect and remove agents inactive for 6+ months
- 📱 **Responsive Dashboard** - Beautiful, modern UI with auto-refresh
- 🚀 **Minimal Dependencies** - Only Chi router and Templ templating engine (plus Go stdlib)
- 📱 **Responsive Dashboard** - Beautiful, modern UI with seamless HTMX-powered updates
- 🚀 **Minimal Dependencies** - Only Chi router, Templ templating, and HTMX (plus Go stdlib)
- ⚙️ **Auto-Generation** - Agent IDs automatically generated from hostname
- 💾 **In-Memory Storage** - Fast, zero-database setup (perfect for small to medium deployments)
- 📡 **Server-Sent Events** - Real-time push notifications from server to web clients
- 📝 **Structured Logging** - Comprehensive slog-based logging throughout the application
## Quick Start
@@ -54,7 +57,7 @@ Binaries are created in the `bin/` directory.
-password securepassword
```
Then access the dashboard at `http://localhost:8080`
Then access the dashboard at `http://localhost:8080`. The interface provides real-time updates - stats refresh instantly when agents report new data!
### Running Agents
@@ -87,7 +90,7 @@ nerd-monitor-agent.bat --server 10.0.20.80:9090 --interval 30s
### Overview Page
Shows all connected agents with real-time metrics:
Shows all connected agents with instant real-time metrics:
- **Status Badge** - Green (Online) or Red (Offline)
- Online: Last report within 15 seconds
@@ -96,16 +99,18 @@ Shows all connected agents with real-time metrics:
- **Memory Usage** - Used / Total with visual progress bar
- **Disk Usage** - Used / Total with visual progress bar
- **Last Seen** - Human-readable timestamp
- **Live Updates** - Stats refresh immediately when agents report new data
### Agent Detail Page
Click any agent hostname to see detailed statistics:
Click any agent hostname to see detailed statistics with live updates:
- Large CPU usage display with progress bar
- Large CPU usage display with progress bar (updates in real-time)
- Memory and disk breakdowns
- Agent ID and detailed metadata
- Last exact timestamp
- Delete button for removing the agent
- **Instant Updates** - CPU stats refresh immediately when agent reports
### Stale Agent Management
@@ -122,10 +127,15 @@ Agents inactive for 6+ months:
- **HTTP Router**: Chi v5 for efficient routing
- **Authentication**: Session-based auth with 24-hour expiry
- **Storage**: In-memory concurrent-safe store (sync.RWMutex)
- **Real-time Broadcasting**: Server-Sent Events (SSE) for instant UI updates
- **Structured Logging**: slog-based logging with debug/info levels
- **API Endpoints**:
- `POST /api/report` - Agent stats reporting
- `POST /api/report` - Agent stats reporting (triggers real-time broadcasts)
- `GET /api/agents` - List all agents
- `GET /api/agents/{id}` - Get specific agent stats
- `GET /api/dashboard/table` - HTML fragment for HTMX dashboard updates
- `GET /api/agents/{id}/stats` - HTML fragment for HTMX agent detail updates
- `GET /api/events` - Server-Sent Events for real-time notifications
### Agent (`cmd/agent/`)
@@ -138,8 +148,9 @@ Agents inactive for 6+ months:
### Views (`views/`)
- **Templ Templates**: Type-safe HTML templating
- **HTMX Integration**: Smooth, instant updates without page refreshes
- **Server-Sent Events**: Real-time push notifications from server
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Auto-Refresh**: Dashboard refreshes every 5 seconds
- **Color-coded Status**: Visual indicators for system health
## Project Structure
@@ -148,28 +159,28 @@ Agents inactive for 6+ months:
nerd-monitor/
├── cmd/
│ ├── agent/
│ │ └── main.go # Agent executable
│ │ └── main.go # Agent executable with slog logging
│ └── server/
│ └── main.go # Server executable
│ └── main.go # Server executable with slog logging
├── internal/
│ ├── api/
│ │ └── api.go # API handlers
│ │ └── api.go # API handlers + real-time broadcaster
│ ├── auth/
│ │ ├── middleware.go # Auth middleware
│ │ ├── middleware.go # Auth middleware with detailed logging
│ │ └── errors.go # Error definitions
│ ├── stats/
│ │ └── stats.go # System stats collection
│ ├── store/
│ │ └── store.go # In-memory agent storage
│ │ └── store.go # In-memory agent storage with logging
│ └── ui/
│ └── handlers.go # Dashboard handlers
│ └── handlers.go # Dashboard handlers + HTMX endpoints
├── views/
│ ├── layout.templ # Base layout template
│ ├── dashboard.templ # Dashboard page
│ ├── agent_detail.templ # Agent detail page
│ ├── layout.templ # Base layout with HTMX + SSE
│ ├── dashboard.templ # Dashboard with real-time updates
│ ├── agent_detail.templ # Agent detail with live stats
│ ├── login.templ # Login page
│ ├── components.templ # Reusable components
│ └── generate.go # Templ code generation
│ └── *_templ.go # Generated Templ code
├── Makefile # Build system
├── go.mod / go.sum # Go dependencies
├── AGENTS.md # Agent guidelines
@@ -231,9 +242,10 @@ Options:
- **Agent Memory**: ~8-10 MB (depending on platform)
- **Server Memory**: Scales with connected agents (~1 MB per 1000 agents)
- **Network**: Minimal bandwidth (~1 KB per report)
- **Dashboard Refresh**: 5 seconds (configurable)
- **Network**: Minimal bandwidth (~1 KB per report + SSE connections)
- **Real-time Updates**: Instant UI updates when agents report stats
- **Agent Reporting**: 15 seconds (configurable)
- **SSE Connections**: Lightweight persistent connections for real-time notifications
## Building for Specific Platforms
@@ -261,6 +273,8 @@ make build-all
- `github.com/go-chi/chi/v5` - HTTP router
- `github.com/a-h/templ` - HTML templating
- `github.com/shirou/gopsutil/v3` - System statistics
- **HTMX** (CDN) - Frontend interactivity and real-time updates
- **Server-Sent Events** (Go stdlib) - Real-time push notifications
### Go Standard Library
@@ -270,6 +284,7 @@ make build-all
- `time` - Timestamps and durations
- `os` - Hostname, signals, I/O
- `crypto/rand` - Token generation
- `log/slog` - Structured logging throughout application
## Troubleshooting
@@ -279,6 +294,15 @@ make build-all
2. Check agent logs for connection errors
3. Ensure correct server address and port
4. Check firewall rules allow outbound connections
5. Check server logs for SSE broadcasting activity
### Stats not updating in real-time
1. Verify browser supports Server-Sent Events (SSE)
2. Check browser developer tools for JavaScript errors
3. Ensure `/api/events` endpoint is accessible (requires authentication)
4. Check server logs for SSE connection/disconnection messages
5. Verify HTMX library loaded correctly
### Agent shows "Offline" immediately
@@ -286,6 +310,7 @@ make build-all
2. Verify server address is reachable: `ping 10.0.20.80`
3. Check if server is listening on the correct port
4. Review server logs for errors
5. Note: Agents are marked offline if no report received in 15 seconds
### Can't login to dashboard
@@ -293,6 +318,7 @@ make build-all
2. Try the default: `admin` / `admin`
3. If changed, restart server with original credentials to reconfigure
4. Check browser cookies are enabled
5. Clear browser cache if SSE connections seem stuck
### Windows agent window appears then closes
@@ -312,6 +338,18 @@ make templ
go run github.com/a-h/templ/cmd/templ@latest generate
```
### Viewing Logs
The application uses structured logging with `slog`. Set log level with:
```bash
# Debug logging (shows all activity)
export GOLOGLEVEL=debug
# Info logging (default, shows important events)
export GOLOGLEVEL=info
```
### Running Tests
```bash
@@ -324,20 +362,42 @@ go test ./...
gofmt -w ./cmd ./internal ./views
```
### Testing Real-time Features
To test SSE and HTMX functionality:
```bash
# Start server
./bin/nerd-monitor-server
# In another terminal, send test stats
curl -X POST "http://localhost:8080/api/report?id=test-agent" \
-H "Content-Type: application/json" \
-d '{"hostname": "test", "cpuUsage": 25.5, "ramUsage": 1000000, "ramTotal": 8000000, "diskUsage": 50000000, "diskTotal": 100000000}'
```
## Contributing
Contributions are welcome! Please follow the code style guidelines in `AGENTS.md`.
## Recent Updates
- ✅ **Real-time Updates**: Instant UI updates via Server-Sent Events and HTMX
- ✅ **Structured Logging**: Comprehensive slog-based logging throughout
- ✅ **Enhanced Monitoring**: Better debugging and operational visibility
## Future Enhancements
- [ ] Database persistence (SQLite/PostgreSQL)
- [ ] Alerting system (email/Slack notifications)
- [ ] Historical data / graphing
- [ ] Historical data / graphing with time-series storage
- [ ] Agent grouping and tagging
- [ ] Custom metric collection
- [ ] TLS/HTTPS support
- [ ] Multi-tenancy
- [ ] API documentation (Swagger)
- [ ] API documentation (Swagger/OpenAPI)
- [ ] Webhook integrations
- [ ] Mobile app companion
## License