8cb33dbc90
- 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
415 lines
12 KiB
Markdown
415 lines
12 KiB
Markdown
# 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 featuring instant real-time updates powered by Server-Sent Events and HTMX.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- 🖥️ **Multi-platform Support** - Deploy agents on Linux, macOS, and Windows (AMD64 & ARM64)
|
|
- ⚡ **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 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
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.23+ (for building)
|
|
- Port 8080 available (configurable)
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build for current OS
|
|
make build
|
|
|
|
# Build for all platforms (Linux, macOS, Windows)
|
|
make build-all
|
|
|
|
# Clean build artifacts
|
|
make clean
|
|
```
|
|
|
|
Binaries are created in the `bin/` directory.
|
|
|
|
### Running the Server
|
|
|
|
```bash
|
|
# Start with default credentials (admin/admin)
|
|
./bin/nerd-monitor-server
|
|
|
|
# Custom configuration
|
|
./bin/nerd-monitor-server \
|
|
-addr 0.0.0.0 \
|
|
-port 8080 \
|
|
-username admin \
|
|
-password securepassword
|
|
```
|
|
|
|
Then access the dashboard at `http://localhost:8080`. The interface provides real-time updates - stats refresh instantly when agents report new data!
|
|
|
|
### Running Agents
|
|
|
|
#### Linux / macOS
|
|
|
|
```bash
|
|
# Connect to local server with default port
|
|
./bin/nerd-monitor-agent --server 10.0.20.80
|
|
|
|
# With custom port
|
|
./bin/nerd-monitor-agent --server 10.0.20.80:9090
|
|
|
|
# With custom reporting interval (default: 15s)
|
|
./bin/nerd-monitor-agent --server myserver:8080 --interval 30s
|
|
```
|
|
|
|
#### Windows
|
|
|
|
Use the batch wrapper to run agents as a background process (no visible terminal):
|
|
|
|
```batch
|
|
REM Run in background with custom server
|
|
nerd-monitor-agent.bat --server 10.0.20.80
|
|
|
|
REM With custom port
|
|
nerd-monitor-agent.bat --server 10.0.20.80:9090 --interval 30s
|
|
```
|
|
|
|
## Dashboard
|
|
|
|
### Overview Page
|
|
|
|
Shows all connected agents with instant real-time metrics:
|
|
|
|
- **Status Badge** - Green (Online) or Red (Offline)
|
|
- Online: Last report within 15 seconds
|
|
- Offline: No report for 15+ seconds
|
|
- **CPU Usage** - Percentage (0-100%)
|
|
- **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 with live updates:
|
|
|
|
- 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
|
|
|
|
Agents inactive for 6+ months:
|
|
- Display warning banner on dashboard
|
|
- Show list of stale agents
|
|
- Bulk select and remove functionality
|
|
- Keep dashboard clean and organized
|
|
|
|
## Architecture
|
|
|
|
### Server (`cmd/server/`)
|
|
|
|
- **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 (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/`)
|
|
|
|
- **Stats Collection**: Uses gopsutil for cross-platform stats
|
|
- **Auto-ID Generation**: Hostname-based ID generation
|
|
- **Reporting**: Configurable interval (default 15 seconds)
|
|
- **Resilience**: Automatic retry on connection failure
|
|
- **Graceful Shutdown**: Handles SIGTERM and SIGINT
|
|
|
|
### 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
|
|
- **Color-coded Status**: Visual indicators for system health
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
nerd-monitor/
|
|
├── cmd/
|
|
│ ├── agent/
|
|
│ │ └── main.go # Agent executable with slog logging
|
|
│ └── server/
|
|
│ └── main.go # Server executable with slog logging
|
|
├── internal/
|
|
│ ├── api/
|
|
│ │ └── api.go # API handlers + real-time broadcaster
|
|
│ ├── auth/
|
|
│ │ ├── middleware.go # Auth middleware with detailed logging
|
|
│ │ └── errors.go # Error definitions
|
|
│ ├── stats/
|
|
│ │ └── stats.go # System stats collection
|
|
│ ├── store/
|
|
│ │ └── store.go # In-memory agent storage with logging
|
|
│ └── ui/
|
|
│ └── handlers.go # Dashboard handlers + HTMX endpoints
|
|
├── views/
|
|
│ ├── 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
|
|
│ └── *_templ.go # Generated Templ code
|
|
├── Makefile # Build system
|
|
├── go.mod / go.sum # Go dependencies
|
|
├── AGENTS.md # Agent guidelines
|
|
├── QUICKSTART.md # Quick start guide
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
Following the guidelines in `AGENTS.md`:
|
|
|
|
- **Imports**: Standard library → third-party → internal (alphabetical)
|
|
- **Formatting**: gofmt standards
|
|
- **Naming**: CamelCase for exports, lowercase for unexported
|
|
- **Error Handling**: Explicit checks, contextual wrapping
|
|
- **Concurrency**: sync.RWMutex for shared state, always defer releases
|
|
- **HTTP**: Chi router with proper status codes and Content-Type headers
|
|
|
|
## Configuration
|
|
|
|
### Server Flags
|
|
|
|
```bash
|
|
./bin/nerd-monitor-server [OPTIONS]
|
|
|
|
Options:
|
|
-addr string
|
|
Server address (default "localhost")
|
|
-port string
|
|
Server port (default "8080")
|
|
-username string
|
|
Admin username (default "admin")
|
|
-password string
|
|
Admin password (default "admin")
|
|
```
|
|
|
|
### Agent Flags
|
|
|
|
```bash
|
|
./bin/nerd-monitor-agent [OPTIONS]
|
|
|
|
Options:
|
|
-server string
|
|
Server URL (required)
|
|
-interval duration
|
|
Reporting interval (default 15s)
|
|
-id string
|
|
Agent ID (auto-generated from hostname if empty)
|
|
```
|
|
|
|
## Default Credentials
|
|
|
|
- **Username**: `admin`
|
|
- **Password**: `admin`
|
|
|
|
⚠️ **Security**: Change these credentials in production!
|
|
|
|
## Performance
|
|
|
|
- **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 + 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
|
|
|
|
```bash
|
|
# Linux AMD64
|
|
GOOS=linux GOARCH=amd64 go build -o bin/nerd-monitor-agent-linux-amd64 ./cmd/agent
|
|
|
|
# macOS ARM64 (Apple Silicon)
|
|
GOOS=darwin GOARCH=arm64 go build -o bin/nerd-monitor-agent-darwin-arm64 ./cmd/agent
|
|
|
|
# Windows AMD64
|
|
GOOS=windows GOARCH=amd64 go build -o bin/nerd-monitor-agent-windows-amd64.exe ./cmd/agent
|
|
```
|
|
|
|
Or use the Makefile:
|
|
|
|
```bash
|
|
make build-all
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
### Production
|
|
|
|
- `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
|
|
|
|
- `encoding/json` - JSON marshaling
|
|
- `net/http` - HTTP server and client
|
|
- `sync` - Concurrent access (RWMutex)
|
|
- `time` - Timestamps and durations
|
|
- `os` - Hostname, signals, I/O
|
|
- `crypto/rand` - Token generation
|
|
- `log/slog` - Structured logging throughout application
|
|
|
|
## Troubleshooting
|
|
|
|
### Agent not appearing in dashboard
|
|
|
|
1. Verify server is running: `http://localhost:8080`
|
|
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
|
|
|
|
1. Check network connectivity between agent and server
|
|
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
|
|
|
|
1. Verify you're using correct credentials
|
|
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
|
|
|
|
1. Use `nerd-monitor-agent.bat` instead of `.exe` directly
|
|
2. The batch wrapper handles background execution
|
|
3. Check task manager to verify agent process is running
|
|
|
|
## Development
|
|
|
|
### Regenerating Templates
|
|
|
|
When modifying `.templ` files:
|
|
|
|
```bash
|
|
make templ
|
|
# or
|
|
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
|
|
go test ./...
|
|
```
|
|
|
|
### Code Formatting
|
|
|
|
```bash
|
|
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 with time-series storage
|
|
- [ ] Agent grouping and tagging
|
|
- [ ] Custom metric collection
|
|
- [ ] TLS/HTTPS support
|
|
- [ ] Multi-tenancy
|
|
- [ ] API documentation (Swagger/OpenAPI)
|
|
- [ ] Webhook integrations
|
|
- [ ] Mobile app companion
|
|
|
|
## License
|
|
|
|
MIT License - See LICENSE file for details
|
|
|
|
## Support
|
|
|
|
- Check `QUICKSTART.md` for common setup issues
|
|
- Review `AGENTS.md` for development guidelines
|
|
- Open an issue for bugs or feature requests
|
|
|
|
---
|
|
|
|
**Made with ❤️ for system administrators and DevOps teams**
|