ms2k/quorate
SHA256
Watch
0
Code Releases Activity

ce7cb702218693d08ea6d83464d2457c9250027c

Browse source
This commit is contained in:
ms2k 2026-11-12 20:46:28 +09:00
commit 34c5f8963c
1 changed files with 145336 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

51
services/cluster-health-api/README.md Normal file
View file

@ -0,0 +1,51 @@
# 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/) |