Nikolay Tatarinov
b5e9b032d7
All checks were successful
CI / ci (push) Successful in 14s
- Renamed the project from "SWatcher" to "Watcher Visio" in the README for clarity. - Added new environment variables `WATCHER_ENDPOINT_NAME` and `WATCHER_INTERFACE_NAME` to `.env.example` for Watcher service configuration. - Updated documentation to reflect the new cache TTL settings for dashboard statistics and source status. - Introduced a new CI section in the README to outline the pipeline configurations for continuous integration.
83 lines
4.2 KiB
Markdown
83 lines
4.2 KiB
Markdown
# Dashboard API and context contract
|
|
|
|
This document describes the structure of data passed to the index template and returned by the dashboard API endpoints. Cache keys are defined in `dashboard/stats.py`.
|
|
|
|
## Index page context (server-rendered)
|
|
|
|
When the index is rendered with full data (e.g. `USE_MOCK_DATA=True` or after JS loads from API), the template receives a context with these top-level keys:
|
|
|
|
| Key | Description |
|
|
|-----|-------------|
|
|
| `region` | `{ "name": str, "hosts_total": int }` |
|
|
| `pcpu` | Physical CPU: `total`, `usage`, `free`, `used_percentage` |
|
|
| `vcpu` | Virtual CPU: `total`, `allocated`, `free`, `allocated_percentage`, `overcommit_ratio`, `overcommit_max` |
|
|
| `pram` | Physical RAM (bytes): `total`, `usage`, `free`, `used_percentage` |
|
|
| `vram` | Virtual RAM (bytes): `total`, `allocated`, `free`, `allocated_percentage`, `overcommit_ratio`, `overcommit_max` |
|
|
| `vm` | VMs: `count`, `active`, `stopped`, `avg_cpu`, `avg_ram`, `density` |
|
|
| `flavors` | `first_common_flavor`, `second_common_flavor`, `third_common_flavor` — each `{ "name": str, "count": int }` or `None`. The `name` may be a human-readable flavor name or a flavor UUID depending on OpenStack. |
|
|
| `audits` | List of audit objects (see below). For template, `migrations`, `host_labels`, `cpu_current`, `cpu_projected` are JSON strings. |
|
|
| `current_cluster` | `{ "host_labels": str (JSON array), "cpu_current": str (JSON array) }` for embedding in the page. |
|
|
| `skeleton` | Optional boolean; when true, stats placeholders are shown and data is loaded via API. |
|
|
|
|
## Single audit object (for template / API response)
|
|
|
|
When serialized for the template or for `api/audits`, each audit has:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `id` | str | Audit UUID |
|
|
| `name` | str | Audit name |
|
|
| `created_at` | str | ISO 8601 datetime |
|
|
| `strategy` | str | Strategy name |
|
|
| `goal` | str | Goal name |
|
|
| `type` | str | e.g. `ONESHOT` |
|
|
| `scope` | str | e.g. `Full Cluster` |
|
|
| `cpu_weight` | str | Weight parameter |
|
|
| `ram_weight` | str | Weight parameter |
|
|
| `migrations` | str (template) / list (API raw) | JSON string of migration list, or list of `{ instanceName, source, destination, flavor, impact }` |
|
|
| `host_labels` | str (template) / list (API raw) | JSON string of host names, or list |
|
|
| `cpu_current` | str (template) / list (API raw) | JSON string of CPU usage per host, or list of numbers |
|
|
| `cpu_projected` | str (template) / list (API raw) | JSON string of projected CPU per host, or list of numbers |
|
|
|
|
For the **index template**, `migrations`, `host_labels`, `cpu_current`, and `cpu_projected` are always JSON strings so they can be embedded in the page. For **api/audits**, `audits` are returned with these four fields as JSON strings (same as template). The **current_cluster** in the API response uses raw lists (see below).
|
|
|
|
## GET /api/stats/
|
|
|
|
Returns a JSON object with the same keys as the index context, **excluding** `audits`, `current_cluster`, and `skeleton`: `region`, `pcpu`, `vcpu`, `pram`, `vram`, `vm`, `flavors`. All numeric values are numbers; sizes are in bytes where applicable.
|
|
|
|
## GET /api/audits/
|
|
|
|
Returns:
|
|
|
|
```json
|
|
{
|
|
"audits": [ /* list of audit objects with migrations, host_labels, cpu_current, cpu_projected as JSON strings */ ],
|
|
"current_cluster": {
|
|
"host_labels": [ "compute-0", "compute-1", ... ],
|
|
"cpu_current": [ 30.5, 42.1, ... ]
|
|
}
|
|
}
|
|
```
|
|
|
|
Here `audits` use the same serialized form as the template (JSON strings for list fields). The `current_cluster` is with **raw lists** (not JSON strings) so the frontend can use them directly without parsing.
|
|
|
|
## GET /api/source-status/
|
|
|
|
Returns:
|
|
|
|
```json
|
|
{
|
|
"prometheus": { "status": "ok" | "error" | "mock", "message"?: "..." },
|
|
"openstack": { "status": "ok" | "error" | "mock", "message"?: "..." }
|
|
}
|
|
```
|
|
|
|
## Cache keys (dashboard/stats.py)
|
|
|
|
- `CACHE_KEY_STATS` — stats for `/api/stats/`
|
|
- `CACHE_KEY_AUDITS` — serialized audits list
|
|
- `CACHE_KEY_CURRENT_CLUSTER` — raw current_cluster (host_labels, cpu_current lists)
|
|
- `CACHE_KEY_SOURCE_STATUS` — source status result
|
|
|
|
TTL for stats and audits is set by `DASHBOARD_CACHE_TTL` in `watcher_visio/settings.py` (default 120 s). TTL for source-status is set by `SOURCE_STATUS_CACHE_TTL` (default 30 s).
|