ADORSYS-GIS / ADORSYS-GIS/lightbridge-authz

[Story]: Continuous aggregates per KPI measure, refresh proven, aggregates never span grains

Aberta
#587 1 comentário 0 reações 0 responsáveis Ver no GitHub
user-story
Linguagem predominante
Rust
Estrelas
0
Forks
1
Merge médio
7h 7min
PRs com merge (30d)
237

Descrição

Parent epic: #581

### Story Statement

As a platform operator, every dashboard KPI reads a named continuous aggregate with a running refresh policy — never a raw-table scan — and each measure has exactly one authoritative source.

### Real Intent

Deliver #491's "10 named continuous aggregates" goal on the new grain tables, under governance#166's rules: one aggregate per measure, exactly one authoritative source per measure, no aggregate spans grains.

### Background and Context

There are zero continuous aggregates today (and there could not be — production had no TimescaleDB, #489/#549). Once the grain tables are real hypertables, the KPI read path must be proven to use aggregates, not assumed: the house failure mode is silent success.

### Source of truth (links)

ADR-0027 Decision 5 · #491 · governance#166 · #489

### Acceptance Criteria

1. A named continuous aggregate per KPI measure (spend, tokens, requests, latency percentiles where supported, active users, acceptance placeholders as sources land), each built on exactly one grain table — no aggregate joins or unions across grains.
2. Refresh policies exist in `timescaledb_information.jobs` and have demonstrably run in the target cluster.
3. For each KPI query, an `EXPLAIN` (captured in the PR) proves the aggregate is read.
4. Aggregates preserve the money discipline: unknown-cost rows counted separately, never coerced to 0 in the rollup.
5. If a percentile aggregate needs `timescaledb_toolkit`, the image decision records it (the `-ha` image question from governance#163); an approximation, if used, is named in the API docs.

### Out of Scope

New KPI definitions (take #491's list); dashboard wiring.

### Dependencies and Blockers

Grain tables + Timescale image landed; per-grain query endpoints (aggregates back them).

### Assumptions

The 90d retention window (#489) is compatible with every aggregate's refresh lag — verify, don't assume, for month-boundary billing queries.

### Implementation Notes

`migrations-usage/`, fail-loud; aggregate names are part of the API surface — document them beside the endpoints they back.

### Test Expectations

A test (or CI check) per aggregate asserting existence + refresh-policy presence; an EXPLAIN-based assertion that the query path hits the aggregate.

### Verification evidence

To be attached on the implementing PR: `timescaledb_information.jobs` output, EXPLAIN captures.

### Human accountable owner

Stephane Segning Lambou

### AI Usage
AI-assisted (Claude): research and drafting. Reviewed and owned by Stephane Segning Lambou.

Guia de contribuição

Abrir o guia de contribuição

Direção de pesquisa

Start in migrations-usage/ by verifying the grain tables and Timescale image dependency. Trace each per-grain query endpoint to its aggregate, then use the per-aggregate existence and refresh-policy checks plus captured EXPLAIN output as the completion criteria; also verify the 90d retention window for month-boundary billing queries and document aggregate names beside the endpoints they back.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
postgresql
Domínio
databases
Tipo de issue
Funcionalidade
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Ativa
Clareza
Razoavelmente clara
Facilidade para iniciantes
45/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.