coulomb/railiance-telemetry
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Complete local Prometheus mapping and record live acceptance blockers

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0e6f1-443f-7783-9920-a16b2ffc467f
This commit is contained in:
tegwick 2026-09-28 09:42:04 +02:00
parent 27df597a39
commit b6d0f78f93
11 changed files with 501 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/prometheus-mapping.md Normal file
View file

@ -0,0 +1,56 @@
# Platform assurance Prometheus mapping
RTEL-WP-0002-T04 supplies `scripts/prometheus_export.py` and
`rules/platform-assurance.json` for integration by rapp-telemetry. These are local
artifacts; no listener, scraper, schedule or Alertmanager route is installed.
Use `contracts/platform-assurance-2026-09-28.json` with current platform reports.
It adds the producer-owned `eso.token-renewal` classification to the original 23
signals. The original contract stays unchanged for existing SQLite databases:
do not change their binding without an explicit migration. Export consumes the
evaluation report itself, not the evidence envelope's `observation`/`evaluation`
wrapper. Unknown fields, signals, states and scope are rejected by the adapter.
```bash
python3 scripts/prometheus_export.py \
--contract contracts/platform-assurance-2026-09-28.json \
/path/to/fresh-platform-report.json
promtool check rules rules/platform-assurance.json
promtool test rules tests/prometheus-rules.json
```
The exporter prints Prometheus text to stdout only after validation; errors use
stderr and exit 2. The package must publish via a temporary file and atomic rename
only on success, or serve successful output through an admitted private exporter.
Never redirect directly over the currently scraped file. No textfile collector
is assumed to exist. The package must select and admit that transport and executor.
Each signal has five `railiance_assurance_state` gauge series, exactly one set to
1. Labels are bounded by the contract (`stream`, `producer`, `signal`, `state`).
No logs, credentials or free-text producer details are exported. The separate
`railiance_assurance_observed_timestamp_seconds` gauge holds original evaluation
time; re-export does not refresh it. Reports older than 900 seconds or in the
future are rejected. State and timestamp metric families must be scraped together
from one complete export for this stream.
`RailianceAssuranceUnhealthy` fires for each non-healthy classification.
`RailianceAssuranceEmissionAbsent` fires for never-seen/disappeared timestamp
series, observation age over 900 seconds, or future observation time. These rules
have no additional `for` delay. They retain source semantics and the proposed
15-minute transport budget. They do not reclassify backup/restore age.
Platform's token-renewal signal currently uses a 36-hour source age threshold.
It reaches the unhealthy rule with all other source classifications. The inbox
request for failed CronJobs or no success for 48 hours (platform RPF-WP-0046-T06)
is not closed by this mapping: exact Job-failure observation and actual delivery
still need owner acceptance. Do not silently replace S3's threshold in Q2.
The JSON rule file is valid Prometheus YAML input. Package integration must wrap
its groups in the selected PrometheusRule/release configuration and verify live
selectors, loading and routing. The warning/owner labels do not identify a
confirmed human recipient. Prometheus loss cannot be detected by its own rules;
an outside-node heartbeat receiver and acknowledged failure/absence drill remain
mandatory. The SQLite inbox and local rule tests cannot satisfy that gate.
Format and validation references: [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/)
and [native rule testing](https://prometheus.io/docs/prometheus/3.7/configuration/unit_testing_rules/).