Skip to Content
LYNKORIADocs

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

CategorySourceGranularity and retentionFreshness
Usage historyRollup tables written incrementally by the API: project_usage_daily and the new project_usage_hourlyDaily rows kept indefinitely; hourly rows kept 35 daysAbout 15 s (buffer flush); participant minutes when each participant session ends
Live activityThe tables the services own: call_sessions, media_participant_sessions, outbox_eventsCurrent stateRead 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-5Backend's retentionNot 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 0004 is 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; peakParticipants uses 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.

On this page