watcher-visio/docs/api_context.md

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:

{
  "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:

{
  "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