feat(platform): time-based usage analytics in governance

[larryro]

Summary

• Replaces the monthly per-user UsageDashboard under Governance → Security & Monitoring → Usage with a time-series analytics page (7/30/90-day presets, daily/weekly/monthly granularity, Requests/Tokens/Cost metric toggle, Top Assistants, Top Models with provider badge, full Per-User table).
• Extends usageLedger with optional agentSlug / model / provider and required granularity; additive indexes only (no renames). All three incrementUsageLedger callsites updated atomically (chat, workflow LLM steps, openai-compat).
• Fixes a pre-existing ISO-8601 weekly period-key bug at year boundaries (e.g. 2023-01-01 was keyed as 2023-W01 instead of 2022-W52) and adds a paginated backfill migration for legacy ledger rows missing granularity.
• Admin-only (read on orgSettings); per-org scope via the existing RLS guard + org switcher. en + de i18n.

Test plan

• npx tsc --noEmit and npm run lint --workspace=@tale/platform both clean
• npx vitest run convex/governance/__tests__/helpers.test.ts — ISO-week boundary cases pass (2023-01-01 → 2022-W52, 2024-12-31 → 2025-W01, 2025-12-29 → 2026-W01)
• Run backfill_ledger_granularity on a deploy with legacy rows; confirm all rows gain a non-null granularity and no duplicates are introduced
• Chat on two assistants with different models; confirm usageLedger has distinct rows per (userId, agentSlug, model) and provider is populated
• Fire two simultaneous completions on the same (agent, model, user, period) — exactly one merged row (race-merge filters work)
• Load Governance → Security & Monitoring → Usage: toggle period / granularity / metric; click a row in Top Assistants / Top Models to filter; dismiss filter chip to clear
• Non-admin member hits the tab → AccessDenied; member of org A with organizationId: B → server-side isAdmin/org-membership guard rejects
• Switch locale to de; all strings render, currency formats locale-aware

Summary by CodeRabbit

Release Notes

New Features

• Added comprehensive usage analytics dashboard displaying total requests, tokens, and costs
• Added usage trend chart with configurable period (7/30/90 days) and granularity (daily/weekly/monthly)
• Added top agents and models tables with usage metrics
• Added per-user usage breakdown view
• Added filtering capabilities by agent, model, and provider with quick-clear options
• Added support for multiple languages in analytics UI

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request introduces a comprehensive usage analytics feature across the platform. It adds multiple new React components for rendering usage metrics (TopAgentsTable, TopModelsTable, UsageTrendChart, UsageSummaryCards, UsersTable) and a main UsageMetricsPage that orchestrates these components with filtering by period, granularity, and metric type. On the backend, it adds a new Convex query getOrgUsageMetrics that aggregates usage data from the ledger with support for optional agent, model, and provider filtering. The usageLedger schema is extended with new optional fields (granularity, agentSlug, model, provider) and corresponding indexes. Existing mutation and action handlers are updated to propagate this new metadata. The old UsageDashboard component is replaced with the new UsageMetricsPage. ISO 8601 week numbering is implemented for weekly period calculations. Translation strings are added for German and English locales.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat(platform): budget limits per user/group #1311: Modifies ledger schema, incrementUsageLedger arguments, and cost tracking infrastructure that directly parallels this PR's usage metadata propagation
• feat(platform): OpenAI Chat Completions API compatibility layer #1251: Updates OpenAI-compat internal actions to propagate model and provider metadata, which aligns with the usage attribution changes in this PR

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.32% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main feature addition: a time-based usage analytics page in the governance section, replacing the static dashboard.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/usage-analytics

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}