quorate/services/cluster-health-api/README.md

Cluster health API

Delivery stage	Scope
Build	Release compilation and OCI assembly; no test execution
Tests	Run separately using the command below

Interface	Behavior
Endpoint	GET /health; no request parameters
Success	application/msgpack; [start, groups]
Start	Unix seconds at UTC midnight, 30 days before the current UTC day
Group	[header, names[], values[][]]; parallel name strings and 30-element value arrays
Values	MessagePack float64 or nil; oldest completed day first; missing samples become nil
Queries	Deployment-configured MetricsQL expressions, sent unchanged; one range query per group
Evaluation	Daily step; 30 evaluation timestamps ending at current UTC midnight; each result describes the preceding day
Validation	Each series has exactly one label; its value becomes the name. Timestamps lie on the daily grid within the requested window
Interpretation	Queries own fraction calculation and incomplete-observation treatment; API does not clamp values
Ordering	Configuration group order and query result series order; display ordering belongs to the page
Cache	Per-process encoded snapshot; refresh failure makes the endpoint unavailable
Responses	200 snapshot; 503 unavailable; 404 other paths; 405 other methods; errors are MessagePack strings
Logging	JSON on stdout; listening, refresh duration/result, process errors

Required environment	Value
LISTEN	Socket address
METRICS_URL	VictoriaMetrics base URL, without trailing slash
PAGE_ORIGIN	CORS origin
REFRESH_SECS	Seconds between completed refreshes
GROUPS	JSON list of [header, query] string tuples

[
  ["Nodes", "avg by (node) (avg_over_time(up{job=\"node-exporter-prometheus-node-exporter\"}[1d]))"],
  ["Public services", "avg by (instance) (avg_over_time(probe_success{job=\"public-health\"}[1d]))"]
]

Example boundary	Value
Collection	Example jobs are configuration, not built-in selectors; public-health probes must exist for that example to return series
Missing history	A series returned for some days has nil for absent days; an entirely absent series cannot be enumerated
Intra-day health	Queries supply fractions; equally spaced 23 passing hourly observations and one failure produce 23/24

Check	Command from repository root
Tests	cargo test --locked --manifest-path services/cluster-health-api/Cargo.toml
Lint	cargo clippy --locked --manifest-path services/cluster-health-api/Cargo.toml --all-targets -- -D warnings
Format	cargo fmt --manifest-path services/cluster-health-api/Cargo.toml --check
Delivery	Declaration
Actions	Build workflow