51 lines
4.7 KiB
Markdown
51 lines
4.7 KiB
Markdown
# 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/) |
|