Analytics Service — Sync Contract
Status: populated Owner: Platform Engineering Last updated: 2026-04-18
1. Per-Projection Policy
| Projection | Policy | Rationale |
|---|---|---|
metrics_hourly | eventually_consistent | Written by event processing; 1–5 min lag behind real-time |
metrics_daily | eventually_consistent | Roll-up runs hourly; max staleness = 1 h |
operator_performance | eventually_consistent | Same as metrics_hourly |
account_usage_daily | eventually_consistent | Rolled up daily; shows yesterday's data for oldest bucket |
2. Offline Behavior
Analytics service has no offline or client-sync concern. All data is server-side. Callers (dashboard, portal) simply retry on 503.
3. Idempotency
All event processing is idempotent via the processed_events dedup table. NATS AckWait (30 s) bounds redelivery. No at-most-once risk.
4. Consistency With Billing
Analytics totals should match billing totals within the processing lag window. A daily reconciliation job compares anlyt.metrics_daily.total_cost with billing.daily_totals and alerts on divergence > 0.01%.
5. Data Freshness SLI
REST API callers should be aware:
/summary,/operators/:id/performance: data is typically 1–5 min stale (hourly bucket lag)./accounts/:id/usage: daily granularity; shows completed days only.- All responses include a
dataAsOffield indicating the timestamp of the most recent aggregate update.