watchdog

🐺 Watchdog

Enterprise-Grade, Cross-Platform System Observability, Automated Diagnostics & Real-Time Terminal Dashboard in Pure Go

Watchdog is an all-in-one system health monitoring, diagnostic automation, and live telemetry CLI. Engineered with a strict Zero-CGO pure Go architecture, Watchdog delivers point-in-time heuristic diagnostics, statistical anomaly detection, persistent local time-series metrics, OpenMetrics/Prometheus exposition, and an interactive AltScreen Bubble Tea terminal user interface—with a minimal footprint ($<1%$ CPU overhead and $<25\text{ MB}$ RSS memory).

🌟 Architectural Pillars

• ⚡ Zero-CGO & Pure Go: Compiles to a single static binary with zero external runtime dependencies (CGO_ENABLED=0).
• 🩺 Automated 10-Rule Diagnostics: Concurrently evaluates system saturation, inode exhaustion, DNS latency, paging spikes, and container health with actionable --fix remediation.
• 🖥️ Interactive 6-Tab AltScreen TUI: Real-time terminal interface with per-core CPU bars, memory breakdown, sparkline history, process sorting/filtering/killing, and container states.
• 🚨 Temporal Alerting Engine: Hysteresis-aware threshold alerts with verification duration windows, suppression cooldowns, and SQLite event auditing.
• 📈 Statistical Anomaly Detection: Pure-Go online Exponentially Weighted Moving Average (EWMA) filtering and rolling $Z$-score metric evaluation ($Z \ge 2.5$).
• 💾 Embedded SQLite Time-Series: Embedded WAL-mode database powered by modernc.org/sqlite with automated background retention pruning.
• 📊 Self-Contained Multi-Format Reports: Single-file dark-themed HTML5 reports with inline SVG vector sparklines (zero external JS/CDN requests), structured JSON, CSV, and ANSI terminal summaries.
• 🌐 Prometheus Exporter & REST API: Native /metrics OpenMetrics endpoint, authenticated REST APIs, and runtime pprof profiling.

🖥️ Terminal Dashboard (TUI)

┌─ Watchdog v1.0.0-rc.1 ──────────────────────────────────────────────── [Host: prod-db-01] ─┐
│ [1] Dashboard  [2] Processes  [3] Storage & Net  [4] Containers  [5] Services  [6] Diag/Alerts │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ CPU [|||||||||||||||||||||||||||||||                    ] 42.5%  Cores: 8  Load: 1.24 1.45 1.10 │
│   Core 0: [||||||||||||||||||||    ] 51.2%    Core 1: [||||||||||||||        ] 36.4%         │
│   Core 2: [||||||||||||||||||||||||] 78.1%    Core 3: [||||||||              ] 22.0%         │
│                                                                                              │
│ Memory [||||||||||||||||||||||||||||||||||              ] 52.6%  8.42 GB / 16.00 GB          │
│ Swap   [||                                              ]  1.5%  128 MB / 8.00 GB            │
│                                                                                              │
│ Disk I/O (nvme0n1)                                    Network (eth0)                         │
│ Read:  1.24 MB/s  ▂▃▅▆▇▆▅▃▂ ▂▃▅                      RX: 42.8 KB/s   ▂▃▅▆▇▆▅▃▂ ▂▃           │
│ Write: 8.45 MB/s   ▂▃▄▅▆▇█▇▆▅▄▃                      TX: 18.2 KB/s   ▂▃▄▅▆▇▆▅▄▃             │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ PID    USER       CPU%    MEM%    VIRT      RES       STATE   TIME       COMMAND             │
│ 1042   postgres   14.2%   8.4%    1.2 GB    540 MB    S       14:22.10   postgres: writer    │
│ 1824   node       8.5%    4.1%    850 MB    280 MB    S       08:12.44   node /app/server.js │
│ 942    redis      1.2%    1.8%    320 MB    112 MB    S       02:40.12   redis-server *:6379 │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ [Tab/1-6] Switch View  [/] Filter  [c/m/p] Sort  [k] Kill  [r] Refresh  [?] Help  [q] Exit   │
└──────────────────────────────────────────────────────────────────────────────────────────────┘

💻 Platform Support Matrix

Watchdog is continuously verified across all major enterprise operating systems and architectures:

📦 Installation

1. Pre-Compiled Binary Releases

Download official release candidate archives for your operating system and architecture from the GitHub Releases page:

Linux (AMD64 / ARM64)

# Download and extract binary
curl -sSL https://github.com/DocHoax/watchdog/releases/download/v1.0.0-rc.1/watchdog_1.0.0-rc.1_linux_amd64.tar.gz | tar -xz
sudo mv watchdog /usr/local/bin/
sudo chmod +x /usr/local/bin/watchdog

macOS (Apple Silicon / Intel)

# macOS Apple Silicon (ARM64)
curl -sSL https://github.com/DocHoax/watchdog/releases/download/v1.0.0-rc.1/watchdog_1.0.0-rc.1_darwin_arm64.tar.gz | tar -xz
sudo mv watchdog /usr/local/bin/
sudo chmod +x /usr/local/bin/watchdog

Windows (PowerShell)

# Download and extract release archive
Invoke-WebRequest -Uri "https://github.com/DocHoax/watchdog/releases/download/v1.0.0-rc.1/watchdog_1.0.0-rc.1_windows_amd64.zip" -OutFile "watchdog.zip"
Expand-Archive -Path "watchdog.zip" -DestinationPath "$env:ProgramFiles\Watchdog" -Force
$env:Path += ";$env:ProgramFiles\Watchdog"

Windows (Command Prompt / cmd.exe)

curl.exe -L -o watchdog.zip "https://github.com/DocHoax/watchdog/releases/download/v1.0.0-rc.1/watchdog_1.0.0-rc.1_windows_amd64.zip"
tar.exe -xf watchdog.zip
watchdog.exe version

2. Build from Source

git clone https://github.com/DocHoax/watchdog.git
cd watchdog
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/watchdog .
./bin/watchdog version

3. Local Go Install

# Clone and install binary directly to $GOPATH/bin
git clone https://github.com/DocHoax/watchdog.git
cd watchdog
go install .

4. Container Deployment

# Build and run locally via Docker
docker build -t watchdog:v1.0.0-rc.1 .
docker run -it --rm --pid=host --net=host \
  -v /proc:/host/proc:ro -v /sys:/host/sys:ro \
  watchdog:v1.0.0-rc.1 dash

⚡ Quickstart Commands

# 1. Launch real-time Terminal Dashboard (TUI)
watchdog dash

# 2. Run automated diagnostic checks across 10 system rules
watchdog diagnose

# 3. Run diagnostic checks with actionable remediation advice
watchdog diagnose --fix

# 4. Generate a standalone, zero-dependency HTML5 health report
watchdog report --format html --output health-report.html --history 2h

# 5. Start Prometheus exporter and authenticated REST API daemon
watchdog server --port 9100 --token "s3cret-token"

# 6. List currently active threshold alerts
watchdog alert list

# 7. Export time-series metrics from embedded SQLite database
watchdog export --format csv --metric cpu_usage_pct --since 24h --output cpu_24h.csv

🛠️ CLI Command Hierarchy

⚙️ Configuration (~/.watchdog/config.yaml)

refresh_interval: 1s

storage:
  enabled: true
  db_path: "~/.watchdog/watchdog.db"
  retention_days: 7
  collection_interval: 10s

alerts:
  cpu:
    enabled: true
    threshold: 90.0                  # Trigger when CPU >= 90%
    duration: 30s                    # Must sustain for 30s
    cooldown: 5m                     # Suppress duplicate alerts for 5m
  memory:
    enabled: true
    threshold: 85.0                  # Trigger when RAM >= 85%
    duration: 30s
    cooldown: 5m
  disk:
    enabled: true
    threshold: 90.0                  # Trigger when partition >= 90%
    duration: 1m
    cooldown: 15m
  process:
    enabled: true
    cpu_threshold: 80.0
    memory_threshold: 70.0
    cooldown: 5m
  network:
    enabled: true
    threshold: 100.0                 # Error packet threshold
    duration: 1m
    cooldown: 10m

anomaly:
  enabled: true
  z_score_threshold: 2.5             # Trigger anomaly when |Z| >= 2.5
  window_size: 60                    # 60-sample rolling ring buffer
  alpha: 0.2                         # EWMA smoothing factor

collectors:
  cpu: true
  memory: true
  disk: true
  network: true
  process: true
  service: true
  port: true
  docker: true
  kubernetes: false

dashboard:
  theme: "default"
  show_per_core_cpu: true
  process_sort_by: "cpu"
  process_limit: 50
  pause_on_start: false

prometheus:
  enabled: false
  port: 9100
  path: "/metrics"

📚 Technical Documentation Suite

🤝 Contributing & Community Governance

We welcome contributions from the community! Please review our governance guidelines before submitting code:

• 📖 Contributing Guidelines
• 🛡️ Security Policy & Vulnerability Reporting
• 🤝 Code of Conduct

📄 License

Watchdog is licensed under the MIT License.