WebSocket Event Hub & Telemetry Scaling

Cockpit uses a real-time event center to stream live server updates to your browser instantly, ensuring that you see status changes without reloading the web page.

---

How the Event Hub Works 📢

💡 Analogy: The Telephones & The Intercom

• Live Connections (WebSockets): Standard web pages work like sending letters: you send a request and wait for a reply. WebSockets work like an open telephone line. Once you open Cockpit in your browser, a telephone call is made to Cockpit's Event Hub endpoint (/api/v1/events). This line stays open so the server can push updates to your screen instantly.
• The Megaphone (pg_notify): If your company runs multiple Cockpit servers for reliability, different admins might be connected to different servers. If a physical host sends a status update to Cockpit Server #1, Server #1 uses a database intercom (megaphone) called pg_notify to shout: "Host A is connected!". Cockpit Server #2 hears this shout and repeats it to all the browser phone lines connected to it.

Here is the flow of a live update:

┌──────────────┐     Phone Call     ┌──────────────┐   Megaphone Shout  ┌──────────────┐     Phone Call     ┌──────────┐
│  Vapor Host  │───────────────────►│  Cockpit #1  │───────────────────►│  Cockpit #2  │───────────────────►│ Browser  │
│  (Physical   │    (WebSocket)     │ (Gets update)│    (pg_notify)     │  (Standby)   │    (WebSocket)     │  Client  │
│   Server)    │                    └──────────────┘                    └──────────────┘                    └──────────┘
└──────────────┘

---

Message Format: The Mail Envelope ✉️

All messages sent over the WebSocket use a standardized layout, resembling a postal envelope:

{
  "type": "<message_type>",   // What is written on the outside of the envelope
  "payload": {
    "kind": "<channel_name>", // The department the letter should go to
    "data": { ... }            // The actual contents of the letter
  }
}

• Actions You Can Send (Outside of Envelope):
  • auth: Sends your login token to prove who you are.
  • subscribe: Tells Cockpit you want to tune in to a specific update channel (e.g., "I want to watch VM #1's charts").
  • unsubscribe: Tells Cockpit to stop sending updates for a channel.
• Responses You Receive:
  • auth: Confirms your login was successful.
  • event: Delivers the live data you subscribed to.
  • error: Informs you if something went wrong (e.g., if you don't have permission to see that VM).

---

Event Channels: Tuning the Radio 📻

💡 Analogy: Radio Frequencies

To get updates, your browser subscribes to specific "channels" (like tuning a radio to a specific frequency to listen to music).

Here are the standard channels you can tune into:

Radio Station Channel	What it broadcasts
host-metrics:<host_id>	Live CPU, Memory, and Disk speed charts for a specific physical server.
vm-events:<host_id>	Real-time VM status changes (e.g., "VM 1 has just been powered off" or "VM 2 crashed").
vm-metrics:<host_id>	A single combined batch of charts for all VMs running on that server.
vm-volume-migration-events:<uuid>:<disk>	A progress bar update (0% to 100%) showing how much of a VM's disk has been moved during storage migration.
task-events	Progress status of general background jobs (like backup creation or system updates).