System Resources Monitor

System Resources Monitor

When enabled with --system-resources, Knightwatch polls hardware metrics every second and exposes them via the /system family of endpoints. It also emits threshold-based events to the Telegram bot and webhook dispatcher.

knightwatch --pid <PID> --system-resources

Default Thresholds

Metric	Warning Threshold
CPU usage	≥ 90%
Memory usage	≥ 90%
Disk usage (per mount)	≥ 90%
Battery charge	≤ 15% (discharging only)

Endpoints

Endpoint	Description
GET /api/system	Full snapshot — CPU, memory, disks, networks, GPUs, battery, thermals, health
GET /api/cpu	Current CPU snapshot only
GET /api/memory	Current memory snapshot only
GET /api/disks	Per-disk snapshots
GET /api/networks	Per-network-interface snapshots
GET /api/gpus	GPU snapshots (empty if no supported GPU detected)
GET /api/battery	Battery snapshot, or 404 if no battery present
GET /api/host-info	Static host information (hostname, OS, kernel, arch, uptime)
GET /api/temperatures	Thermal sensor readings

Note: On Windows, /api/temperatures requires running the app as administrator.

The health field on /api/system can be healthy, warning, or critical.

System Resources Commands

When the server is started with --allow-system-resources-commands, the following write endpoints become available.

Authentication required. All system resources command endpoints always require authentication, regardless of whether --enable-auth is set.

knightwatch --system-resources --allow-system-resources-commands

Command Endpoints

Endpoint	Description
POST /api/resources/thresholds	Update alert thresholds for CPU, memory, disk, and battery
POST /api/resources/refresh-mask	Update which subsystems are collected on each tick
POST /api/resources/poll/pause	Pause the polling loop
POST /api/resources/poll/resume	Resume the polling loop
POST /api/resources/poll/interval	Change the polling interval

Updating Thresholds

Override the default warning thresholds at runtime:

POST /api/resources/thresholds
Content-Type: application/json
 
{
  "cpu_warn": 85.0,
  "memory_warn": 90.0,
  "disk_warn": 95.0,
  "battery_low": 20.0
}

All fields are optional — omit any you don't want to change. Returns 200 OK.

Updating the Refresh Mask

Control which subsystems are collected on each polling tick:

POST /api/resources/refresh-mask
Content-Type: application/json
 
{
  "cpu": true,
  "memory": true,
  "disks": true,
  "networks": true,
  "temperatures": false,
  "gpus": false
}

Returns 200 OK.

Controlling the Poll Loop

Pause snapshot collection:

POST /api/resources/poll/pause

Resume at the current interval:

POST /api/resources/poll/resume

Change the polling interval (takes effect immediately):

POST /api/resources/poll/interval
Content-Type: application/json
 
{ "interval_ms": 2000 }

---

Webhook Events

Event	Description	Key data fields
resources.initial_snapshot	First hardware snapshot after startup	snapshot
resources.tick	Periodic hardware snapshot	snapshot
resources.cpu_threshold_exceeded	CPU crossed warning threshold	usage_percent, threshold
resources.memory_threshold_exceeded	Memory crossed warning threshold	usage_percent, threshold
resources.disk_threshold_exceeded	Disk crossed warning threshold	mount_point, usage_percent, threshold
resources.battery_low	Battery charge below threshold	charge_percent, threshold
resources.battery_state_changed	Battery state changed	state

Telegram Notifications

When both --system-resources and --telegram are enabled, the bot sends alerts for:

• ⚠️ CPU threshold exceeded — aggregate CPU usage above 90%
• ⚠️ Memory threshold exceeded — memory usage above 90%
• ⚠️ Disk threshold exceeded — a mount point usage above 90%
• 🔋 Battery low — charge below 15% while discharging
• 🔌 Battery state changed — plugged in, unplugged, or full