ADR 025: Where console analytics come from
- Status: Accepted
- Owner: Eng lead
- Date: 2026-11-14
Context
The console shows usage history, live activity and operational health. Each has a different natural source, and Prometheus is not a suitable store for per-project history (project labels are high-cardinality and its retention is short). No monitoring backend is deployed yet (PD-5).
Decision
| Category | Source | Granularity and retention | Freshness |
|---|---|---|---|
| Usage history | Rollup tables written incrementally by the API: project_usage_daily and the new project_usage_hourly | Daily rows kept indefinitely; hourly rows kept 35 days | About 15 s (buffer flush); participant minutes when each participant session ends |
| Live activity | The tables the services own: call_sessions, media_participant_sessions, outbox_events | Current state | Read on request; the console polls every 15 s while the tab is visible |
| Operational metrics (latency percentiles, CPU, memory, sockets, LiveKit node health) | Prometheus, after PD-5 | Backend's retention | Not shown until the backend exists; listed as unavailable in the catalog |
Rules:
- Rollups are additive upserts at write time; page loads never scan raw messages, calls or requests.
- Hourly data starts when migration
0004is applied and is never backfilled. The API returns the first recorded hour so the console labels charts "data since …" instead of drawing zeros before collection began. - Aggregations follow the metric: counts are summed;
peakParticipantsuses the maximum, never a sum; error rate is computed from summed requests and errors, never by averaging rates. - Usage numbers are operational, not a billing ledger. Quotas are enforced from live state (concurrent rooms counted in
call_sessions, token rates in Redis), and the console's quota views read the same tables and limits, so the two never disagree. - Every metric shown is defined in
@lynkoria/contracts/catalog(METRICS), which generates the metrics catalog and the console's info popovers. - Real-time updates use polling through the admin API (paused in background tabs). No browser connects to an internal service, and no new streaming channel is added for the console.
Consequences
Hourly history covers 35 days; longer views use daily buckets. Online-user counts are not shown: presence lives in per-user Redis keys and there is no per-environment counter to read cheaply.