railiance-telemetry/docs/prometheus-mapping.md

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.

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 and native rule testing.