diff --git a/docs/WINDSURF/TELEMETRY_ROADMAP.md b/docs/WINDSURF/TELEMETRY_ROADMAP.md index 2934c5c3..eb43de91 100644 --- a/docs/WINDSURF/TELEMETRY_ROADMAP.md +++ b/docs/WINDSURF/TELEMETRY_ROADMAP.md @@ -1,6 +1,6 @@ # Client Telemetry — Implementation Roadmap -> **Status:** Phase 2 complete, Phase 3 pending +> **Status:** Phase 2 in progress (Android pending), Phase 3 pending > **Last updated:** 2026-02-17 > **Design doc:** [`CLIENT_TELEMETRY_DESIGN.md`](./CLIENT_TELEMETRY_DESIGN.md) > **Repos:** `learning_ai_common_plat` (platform-service) · `learning_voice_ai_agent` (all clients + dashboards) @@ -82,6 +82,18 @@ - [x] `/api/telemetry/ingest/route.ts` — Server-side proxy to platform-service ([`130e1d6`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/130e1d6)) - [x] `providers.tsx` — `initTelemetry()` called on app mount ([`130e1d6`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/130e1d6)) +### Tracker Dashboard (Not Started) + +- [ ] Add `telemetry.ts` client module (same pattern as user dashboard) +- [ ] Add `/api/telemetry/ingest/route.ts` proxy +- [ ] `initTelemetry()` in providers or layout + +### Admin Dashboard Self-Telemetry (Not Started) + +- [ ] Add `telemetry.ts` client module to admin-dashboard-web +- [ ] Add `/api/telemetry/admin-ingest/route.ts` proxy (separate from admin query route) +- [ ] Track admin page views, filter usage, policy changes + ### Android (Not Started) - [ ] `TelemetryClient.kt` — Kotlin telemetry client for Android keyboard + main app @@ -141,44 +153,65 @@ │ iOS Keyboard Ext │ │ iOS Main App │ │ Desktop (Python) │ │ LysnrTelemetry │───▶│ TelemetryService │ │ PlatformTelemetry│ │ (App Group queue) │ │ (drains queue) │ │ (urllib POST) │ -└─────────┬───────────┘ └──────────┬───────────┘ └────────┬──────────┘ - │ │ │ - │ POST /api/telemetry/events │ - ▼ ▼ ▼ +└─────────────────────┘ └──────────┬───────────┘ └────────┬──────────┘ + Full Access ON ──┐ │ │ + direct POST │ │ │ + ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ -│ Platform Service (Fastify) │ -│ POST /api/telemetry/events — batch ingestion │ -│ GET /api/telemetry/config — client collection config │ -│ GET /api/telemetry/query — admin event search │ -│ GET /api/telemetry/clusters — error cluster aggregation │ -│ CRUD /api/telemetry/policies — collection policy management │ -│ DELETE /api/telemetry/gdpr/:id — GDPR erasure │ +│ Platform Service (Fastify, port 4003) │ +│ POST /api/telemetry/events — batch ingestion │ +│ GET /api/telemetry/config — client collection config │ +│ GET /api/telemetry/query — admin event search │ +│ GET /api/telemetry/clusters — admin error clusters │ +│ CRUD /api/telemetry/policies — collection policy management │ +│ DELETE /api/telemetry/user/:userId — GDPR erasure │ └────────────────────────────┬────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Azure Cosmos DB │ -│ telemetry_events pk: productId:yyyyMM:platform │ -│ telemetry_error_clusters pk: /productId │ -│ telemetry_collection_policies pk: /productId │ -└─────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────┐ -│ Admin Dashboard (Next.js) │ -│ /ops/client-logs — event viewer + error clusters │ -│ /ops/telemetry-policies (Phase 3) — policy builder UI │ +│ telemetry_events partitionKeyPath: /pk │ +│ pk value = productId:yyyyMM:platform (e.g. lysnrai:202602:ios) │ +│ telemetry_error_clusters partitionKeyPath: /pk │ +│ pk value = productId:platform:module (e.g. lysnrai:ios:dictation)│ +│ telemetry_collection_policies partitionKeyPath: /productId │ └─────────────────────────────────────────────────────────────────────────┘ -┌─────────────────────┐ -│ Web User Dashboard │ -│ telemetry.ts │──▶ POST /api/telemetry/ingest ──▶ platform-service -│ (sendBeacon) │ -└─────────────────────┘ +┌─────────────────────────┐ ┌──────────────────────┐ +│ Admin Dashboard │ GET │ User Dashboard │ POST +│ /ops/client-logs │─────────▶│ /api/telemetry/ │─────────▶ platform +│ (queries via │ query/ │ ingest │ /events -service +│ platform-service API) │ clusters│ (browser → proxy) │ +└─────────────────────────┘ └──────────────────────┘ + +┌───────────────────────┐ +│ Android (Phase 2) │ ← Not yet implemented +│ TelemetryClient.kt │──▶ POST /api/telemetry/events ──▶ platform-service +│ (SharedPreferences) │ +└───────────────────────┘ ``` --- +## Bugs Found During Review + +The following bugs were discovered during systematic review of the roadmap against actual code and fixed: + +| # | Severity | Issue | Fix | +| --- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| 1 | **High** | Desktop Python `id` used `uuid.uuid4().hex` (32 hex, no dashes) — fails Zod `.uuid()` server validation | Changed to `str(uuid.uuid4())` | +| 2 | **High** | Web telemetry `osFamily='web'` not in Zod `OsFamilyEnum` — fails server validation | Changed to `'other'` | +| 3 | **Medium** | Status said "Phase 2 complete" but Android is all unchecked | Fixed status line | +| 4 | **Medium** | Architecture diagram showed wrong pk for `telemetry_error_clusters` (`/productId` → actual `/pk` = `productId:platform:module`) | Fixed diagram | +| 5 | **Medium** | Tracker dashboard telemetry missing from roadmap entirely | Added as Phase 2 pending | +| 6 | **Medium** | Admin dashboard self-telemetry (page views) not mentioned | Added as Phase 2 pending | +| 7 | **Low** | Architecture diagram missing Android client box | Added with "not yet implemented" note | +| 8 | **Low** | Architecture diagram implied Admin reads Cosmos directly (it queries Platform Service) | Fixed data flow arrows | +| 9 | **Low** | Web `telemetry.ts` JSDoc said "via the admin dashboard proxy" (wrong dashboard) | Fixed to "user dashboard's /api/telemetry/ingest proxy" | +| 10 | **Low** | Commit log missing roadmap doc commit | Added | + +--- + ## Commit Log | Date | Repo | Commit | Description | @@ -190,3 +223,5 @@ | 2026-02-17 | voice-agent | [`d202f94`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/d202f94) | Admin dashboard Client Logs page + sidebar nav | | 2026-02-17 | voice-agent | [`a173baa`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/a173baa) | iOS main app TelemetryService + Desktop Python platform_telemetry | | 2026-02-17 | voice-agent | [`130e1d6`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/130e1d6) | Web user-dashboard telemetry client + ingest proxy | +| 2026-02-17 | common-plat | [`c3d6977`](https://github.com/saravanakumardb1/learning_ai_common_plat/commit/c3d6977) | Telemetry roadmap doc (this file) | +| 2026-02-17 | voice-agent | [`ae77438`](https://github.com/saravanakumardb1/learning_voice_ai_agent/commit/ae77438) | Fix: desktop uuid format + web osFamily — pass Zod validation |