Stats Topic

Real-time system performance metrics via WebSocket

The stats topic provides real-time system performance data including CPU, memory, GPU, disks, and network metrics.

Subscribe to all system metrics:

{ "op": "subscribe", "data": { "topics": ["stats"] } }

This automatically includes: cpu, memory, gpu, disks, network.

Granular Stats

Subscribe to specific metrics only:

{ "op": "subscribe", "data": { "topics": ["stats.cpu", "stats.memory"] } }

Backward Compatible

Legacy topic names (cpu, memory, gpu, disks, network) still work.

Available Sub-Topics

Topic	Alias	Description
`stats.cpu`	`cpu`	CPU load, temperature, speed
`stats.memory`	`memory`	RAM usage (used, free, percent)
`stats.gpu`	`gpu`	GPU load, temperature, VRAM
`stats.disks`	`disks`	Disk space per mount point
`stats.network`	`network`	Total bytes sent/received

Event: `system_stats`

Broadcasts at the configured interval (default: 1000ms).

{
  "type": "system_stats",
  "data": {
    "timestamp": 1706140800,
    "uptime": 86400,
    "cpu": {
      "current_load": 23.5,
      "current_temp": 0.0,
      "current_speed": 3.6
    },
    "memory": {
      "used": 8589934592,
      "free": 8589934592,
      "used_percent": 50.0
    },
    "gpu": {
      "current_load": 15.2,
      "current_temp": 45.0,
      "current_memory": 2048
    },
    "disks": [
      {
        "fs": "C:",
        "used": 107374182400,
        "available": 107374182400,
        "used_percent": 50.0
      }
    ],
    "network": {
      "bytes_sent": 1073741824,
      "bytes_recv": 2147483648
    }
  }
}

Filtered Data

Only fields you subscribed to will be populated. Unsubscribed fields are null or omitted.

Field Reference

CPU

Field	Type	Description
`current_load`	float	CPU usage percentage (0-100)
`current_temp`	float	Temperature in Celsius (if available)
`current_speed`	float	Current clock speed in GHz

Memory

Field	Type	Description
`used`	int	Used memory in bytes
`free`	int	Free memory in bytes
`used_percent`	float	Usage percentage (0-100)

GPU

Field	Type	Description
`current_load`	float	GPU usage percentage (0-100)
`current_temp`	float	Temperature in Celsius
`current_memory`	int	Used VRAM in MB

Disks (Array)

Field	Type	Description
`fs`	string	Mount point (e.g., "C:", "/home")
`used`	int	Used space in bytes
`available`	int	Available space in bytes
`used_percent`	float	Usage percentage (0-100)

Network

Field	Type	Description
`bytes_sent`	int	Total bytes transmitted
`bytes_recv`	int	Total bytes received

Configuration

In config.json:

{
  "websocket": {
    "stats": {
      "enabled": true,
      "interval_ms": 1000
    }
  }
}

Example Use Cases

1. System Monitor Dashboard

Build a real-time dashboard showing CPU, memory, and GPU usage.

const ws = new WebSocket("ws://localhost:9990/api/ws");

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      op: "subscribe",
      data: { topics: ["stats"] },
    }),
  );
};

ws.onmessage = (event) => {
  const { type, data } = JSON.parse(event.data);
  if (type === "system_stats") {
    updateCpuGauge(data.cpu?.current_load);
    updateMemoryBar(data.memory?.used_percent);
    updateGpuGauge(data.gpu?.current_load);
  }
};

2. Low-Bandwidth Mode

Only subscribe to what you need for a minimal widget:

// Only CPU and memory - no GPU, disks, or network
ws.send(
  JSON.stringify({
    op: "subscribe",
    data: { topics: ["stats.cpu", "stats.memory"] },
  }),
);

3. Disk Space Alert

Monitor disk usage and alert when running low:

ws.send(
  JSON.stringify({
    op: "subscribe",
    data: { topics: ["stats.disks"] },
  }),
);

ws.onmessage = (event) => {
  const { type, data } = JSON.parse(event.data);
  if (type === "system_stats" && data.disks) {
    for (const disk of data.disks) {
      if (disk.used_percent > 90) {
        alert(`${disk.fs} is ${disk.used_percent.toFixed(1)}% full!`);
      }
    }
  }
};

4. Network Traffic Graph

Track bandwidth over time:

const history = [];

ws.onmessage = (event) => {
  const { type, data } = JSON.parse(event.data);
  if (type === "system_stats" && data.network) {
    history.push({
      time: data.timestamp,
      sent: data.network.bytes_sent,
      recv: data.network.bytes_recv,
    });
    renderGraph(history);
  }
};