# 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     |

```json
[
  ["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](../project-delivery/k8s/deliveries/cluster-health.yaml)                                       |
| Actions  | [Build workflow](../project-delivery/actions/cluster-health/)                                               |