Skip to content

Commit 764c83d

Browse files
sai-kumar-peddireddysai-kumar-peddireddy
authored
Event hub doc (#335)
docs: add Events Hub user guides and reference documentation Introduces a new documentation section for the Events Hub WebSocket service in `docs/docs/devops/events-hub/`. - Add `overview.md`: Covers WebSocket protocol details, authentication (Bearer/API Key), connection limits, and available channels (`global`, `pdfm`, `orchestrator`, `health`). - Add "How-to" guides: - `how-to-monitor-VM-events.md`: Subscribing to VM lifecycle events with JSON payload examples. - `how-to-monitor-orchestrator-events.md`: Monitoring cluster-level events like host health and VM state changes. - `how-to-send-heartbeat.md`: Implementing ping/pong logic to keep connections alive. - `how-to-send-unsubscribe-requests.md` & `how-to-know-my-client-id.md`: Managing subscriptions and client identity. - Visualizations: Integrate Mermaid.js todocs: add Events Hub user guides and reference documentation
1 parent 93b5b7e commit 764c83d

File tree

33 files changed

+2416
-101
lines changed

33 files changed

+2416
-101
lines changed

‎docs/Parallels_Desktop_API.postman_collection.json‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,87 @@
9292
}
9393
]
9494
},
95+
{
96+
"name": "Events Hub",
97+
"item": [
98+
{
99+
"name": "Subscribe (WebSocket handshake)",
100+
"request": {
101+
"method": "GET",
102+
"header": [
103+
{
104+
"key": "Authorization",
105+
"value": "Bearer {{token}}"
106+
},
107+
{
108+
"key": "X-Source-Id",
109+
"value": "Postman"
110+
}
111+
],
112+
"url": {
113+
"raw": "{{protocol}}://{{host}}/api/v1/ws/subscribe?event_types=pdfm,health",
114+
"protocol": "{{protocol}}",
115+
"host": [
116+
"{{host}}"
117+
],
118+
"path": [
119+
"api",
120+
"v1",
121+
"ws",
122+
"subscribe"
123+
],
124+
"query": [
125+
{
126+
"key": "event_types",
127+
"value": "pdfm,health"
128+
}
129+
]
130+
},
131+
"description": "Opens a WebSocket subscription to the Events Hub."
132+
},
133+
"response": []
134+
},
135+
{
136+
"name": "Unsubscribe from channels",
137+
"request": {
138+
"method": "POST",
139+
"header": [
140+
{
141+
"key": "Authorization",
142+
"value": "Bearer {{token}}"
143+
},
144+
{
145+
"key": "Content-Type",
146+
"value": "application/json"
147+
},
148+
{
149+
"key": "X-Source-Id",
150+
"value": "Postman"
151+
}
152+
],
153+
"body": {
154+
"mode": "raw",
155+
"raw": "{\n \"client_id\": \"{{events_client_id}}\",\n \"event_types\": [\"pdfm\"]\n}"
156+
},
157+
"url": {
158+
"raw": "{{protocol}}://{{host}}/api/v1/ws/unsubscribe",
159+
"protocol": "{{protocol}}",
160+
"host": [
161+
"{{host}}"
162+
],
163+
"path": [
164+
"api",
165+
"v1",
166+
"ws",
167+
"unsubscribe"
168+
]
169+
},
170+
"description": "Removes one or more channels from an active Events Hub client."
171+
},
172+
"response": []
173+
}
174+
]
175+
},
95176
{
96177
"name": "Config",
97178
"item": [

‎docs/_data/docs_devops_menu.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,17 @@
4545
link: /docs/devops/reverse-proxy/getting-started/
4646
- name: Configuration
4747
link: /docs/devops/reverse-proxy/configuration/
48+
- label: Events Hub
49+
items:
50+
- name: Overview
51+
link: /docs/devops/events-hub/overview/
52+
- name: Monitor VM Events
53+
link: /docs/devops/events-hub/how-to-monitor-VM-events/
54+
- name: Monitor Orchestrator Events
55+
link: /docs/devops/events-hub/how-to-monitor-orchestrator-events/
56+
- name: Sending Heartbeats
57+
link: /docs/devops/events-hub/how-to-send-heartbeat
58+
- name: Knowing My Client ID
59+
link: /docs/devops/events-hub/how-to-know-my-client-id/
60+
- name: Sending Unsubscribe Requests for Events channel
61+
link: /docs/devops/events-hub/how-to-send-unsubscribe-requests/

‎docs/_includes/head.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66
<link rel="shortcut icon" type="image/png" {% if site.favicon %} href="{{ site.favicon | relative_url }}" {% else %} href="{{ site.baseurl }}/favicon.ico" {% endif %} />
77
<script defer src="https://unpkg.com/[email protected]/dist/cdn.min.js"></script>
88
<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300' rel='stylesheet' type='text/css'>
9+
<script type="module">
10+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
11+
mermaid.initialize({ startOnLoad: true });
12+
</script>
913
<script type="text/javascript">
1014
// Clarity Consent Management
1115
window.ClarityConsent = {

‎docs/docs/devops/events-hub/how-to-know-my-client-id.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
layout: page
3+
title: Events Hub
4+
subtitle: How To Know My Client ID
5+
menubar: docs_devops_menu
6+
show_sidebar: false
7+
toc: true
8+
---
9+
# How to Know My Client ID
10+
When you connect to the Events Hub WebSocket service, each client is assigned a unique Client ID. This Client ID is essential for identifying your connection and managing events. Here’s how you can find out your Client ID.
11+
12+
## Steps to Know Your Client ID
13+
1. First, ensure you have connected to the Events Hub WebSocket service and subscribed to the desired event channels. Refer to the [How to Send Heartbeats]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/how-to-send-heartbeat) guide for connection instructions. When you send a ping message to the health channel, you will receive a pong response that includes your Client ID.
14+
2. Once connected, send a heartbeat ping message to the `health` event channel. A heartbeat message is a simple JSON object like this:
15+
```json
16+
{"event_type": "health","message":"ping"}
17+
```
18+
3. After sending the ping message, you will receive a pong response from the server. The pong response will contain your Client ID in the `client_id` field. A typical pong response looks like this:
19+
```json
20+
{
21+
"id":"1495c450ab281318efc6b63482fde92630b66c0bf66acd5073fdc3a44402be67","ref_id":"cbd91850fad5fc286caa89916b081c9d34c4b7bde2ce4ce4392f47527a9cc27",
22+
"event_type":"health",
23+
"timestamp":"2025-12-12T15:57:55.570578Z",
24+
"message":"pong",
25+
"client_id":"d24c0350-936d-4c7a-8948-36f42343c87c"
26+
}
27+
```
28+
4. Locate the `client_id` field in the pong response to find your unique Client ID.
29+
5. You can now use this Client ID for managing your connection and subscriptions within the Events Hub.
30+
31+
Alternatively, you can find your Client ID in the initial connection confirmation message you receive when you first connect to the Events Hub. This message includes a `body` section that contains the `client_id`.
32+
33+
You can also send a client info request to the server to retrieve your Client ID. Send a JSON message like this:
34+
35+
```json
36+
{"event_type": "system","message":"client-id"}
37+
```
38+
39+
The server will respond with a message containing your Client ID.
40+
```json
41+
{
42+
"id":"73841562a9753aa06a88623a1d5d47c5e831a6911e4a79d80910d495c4ecedd7","ref_id":"4232a7922d4c21f08f25c0da09b07b74a054d033948cbf53fbaf17808b45069f",
43+
"event_type":"system",
44+
"timestamp":"2025-12-15T09:30:57.021027Z",
45+
"message":"client-id",
46+
"body":
47+
{
48+
"client-id":"26369eda-4802-49f7-a07f-2292721d1724"
49+
},
50+
"client_id":"26369eda-4802-49f7-a07f-2292721d1724"
51+
}
52+
```
53+
54+
## FAQ
55+
#### Can I change my Client ID?
56+
No, the Client ID is automatically assigned by the Events Hub service and cannot be changed.
57+
#### Is the Client ID persistent across sessions?
58+
No, the Client ID is unique to each connection session. A new Client ID is assigned each time you connect to the Events Hub.
59+
#### How is the Client ID used?
60+
The Client ID is used if you want to unsubscribe from specific event channels or manage your subscriptions.
61+
#### What if I lose my Client ID?
62+
Send another heartbeat ping message to the `health` channel or a client info request to retrieve your Client ID again.
63+
#### Can I use the Client ID for multiple connections?
64+
No, each connection to the Events Hub has its own unique Client ID. You cannot use the same Client ID for multiple connections.
65+
#### Where can I find more information about unsubscribing using Client ID?
66+
Refer to the [How To Send Unsubscribe Requests for Events channel]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/how-to-send-unsubscribe-requests) guide for detailed instructions on how to use your Client ID to unsubscribe from event channels.
67+
68+
Refer to the troubleshooting section in the [overview guide]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/overview#troubleshooting--faq) for common issues.

‎docs/docs/devops/events-hub/how-to-monitor-VM-events.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
layout: page
3+
title: Events Hub
4+
subtitle: How to Monitor VM Events
5+
menubar: docs_devops_menu
6+
show_sidebar: false
7+
toc: true
8+
---
9+
# How to Monitor VM Events
10+
11+
To monitor VM events in real-time, you can subscribe to the `pdfm` event channel using the Events Hub WebSocket service. This allows you to receive instant notifications about VM lifecycle changes, such as when a VM is started, stopped, or deleted.
12+
13+
<div class="mermaid">
14+
sequenceDiagram
15+
participant Client
16+
participant Server
17+
Client->>Server: Connect & Subscribe (pdfm)
18+
Server-->>Client: Subscription Confirmed
19+
Note over Server: VM State Changes (e.g. Running -> Stopped)
20+
Server-->>Client: Event: VM_STATE_CHANGED
21+
</div>
22+
23+
## Steps to Monitor VM Events
24+
25+
1. **Obtain Your Token**: Get a Bearer token or API Key from your
26+
administrator, or refer to the
27+
[API reference]({{ site.url }}{{ site.baseurl }}/docs/devops/restapi/reference/api_keys).
28+
2. **Connect to the Events Hub**:
29+
You can subscribe to multiple event channels during connection, like `pdfm,health`, to receive both VM events and health check events. For this example, we are subscribing to `pdfm`.
30+
31+
For simplicity, the examples below use
32+
`wscat` (a popular WebSocket client) to connect and subscribe to VM events.
33+
You can use any WebSocket client of your choice. Refer to the REST API
34+
[reference]({{ site.url }}{{ site.baseurl }}/docs/devops/restapi/reference/events/#v1-ws-subscribe-get)
35+
if you want to use another client.
36+
37+
- Install `wscat` (if not already installed):
38+
39+
```bash
40+
brew install node
41+
npm install -g wscat
42+
```
43+
44+
- Connect and subscribe to VM events on the `pdfm` channel:
45+
46+
```bash
47+
wscat -H "Authorization: Bearer <YOUR_TOKEN>" -c "ws://<YOUR_HOST>/api/v1/ws/subscribe?event_types=pdfm"
48+
```
49+
50+
- Note: Use `wss://` instead of `ws://` if your server
51+
is configured for TLS.
52+
3. **Verify Subscription**: Upon successful connection, you will receive a
53+
confirmation message indicating that you are subscribed to the `pdfm`
54+
channel.
55+
56+
Example confirmation message:
57+
58+
```json
59+
{
60+
"id": "985763c36f1a7f04663353ceb5515afaa497414ebec3226e9fa0d475b7713e34",
61+
"event_type": "global",
62+
"timestamp": "2025-12-11T13:04:37.484843Z",
63+
"message": "WebSocket connection established; subscribed to global by default",
64+
"body": {
65+
"client_id": "338a28f7-666e-46e1-8e7d-4feba5edc061",
66+
"subscriptions": [
67+
"pdfm",
68+
"global"
69+
]
70+
}
71+
}
72+
```
73+
74+
4. **Monitor VM Events**: You will start receiving real-time VM events. Each
75+
event contains details about VM state changes (e.g., when a VM starts,
76+
stops, or is deleted).
77+
78+
Example VM state change event:
79+
80+
```json
81+
{
82+
"id": "60adab5b984894719ecb83a0ad7da3d2027a63932c65d0f0585f3762083aa4a1",
83+
"event_type": "pdfm",
84+
"timestamp": "2025-12-11T13:21:21.514683Z",
85+
"message": "VM_STATE_CHANGED",
86+
"body": {
87+
"previous_state": "suspended",
88+
"current_state": "resuming",
89+
"vm_id": "fb83295e-0ccb-46b1-8205-b03997f82b00"
90+
}
91+
}
92+
```
93+
94+
### JSON Object Schemas
95+
96+
On VM state change event:
97+
98+
```go
99+
type VmStateChange struct {
100+
PreviousState string `json:"previous_state"`
101+
CurrentState string `json:"current_state"`
102+
VmID string `json:"vm_id"`
103+
}
104+
```
105+
106+
On VM added event:
107+
108+
```json
109+
{
110+
"id": "7cbc843fd99e2965fd4039410a0e20c2984b8b9c8889991954751d66b90cabb1",
111+
"event_type": "pdfm",
112+
"timestamp": "2025-12-12T12:12:14.164146Z",
113+
"message": "VM_ADDED",
114+
"body": {
115+
"vm_id": "ae032783-53d3-49c3-babf-1475589d9a7b",
116+
"new_vm": {
117+
"name": "My New VM",
118+
"os_type": "ubuntu",
119+
"state": "running"
120+
}
121+
}
122+
}
123+
```
124+
125+
On VM removed event:
126+
127+
```json
128+
{
129+
"id": "4f5e6d7c8b9a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aa",
130+
"event_type": "pdfm",
131+
"timestamp": "2025-12-12T13:15:20.123456Z",
132+
"message": "VM_REMOVED",
133+
"body": {
134+
"vm_id": "ae032783-53d3-49c3-babf-1475589d9a7b"
135+
}
136+
}
137+
```
138+
139+
### FAQ
140+
#### What types of VM events can I monitor?
141+
You can monitor various VM events such as state changes (started, stopped, suspended, resumed..etc), additions, and deletions.
142+
#### Can I use other WebSocket clients besides `wscat`?
143+
Yes, you can use any WebSocket client that supports custom headers for authentication. Just ensure you include the appropriate authorization header.
144+
#### Is it possible to monitor events for multiple VMs?
145+
Yes, by subscribing to the `pdfm` event type, you will receive events for all VMs managed by the server.
146+
147+
Refer troubleshooting section in the [overview guide]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/overview#troubleshooting--faq) for common issues.

0 commit comments

Comments
 (0)