docs: fix 10 gaps in telemetry roadmap — code bugs, diagram, missing dashboards
This commit is contained in:
saravanakumardb1
parent
c3d697711e
commit
dcc0befb8c
@ -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 |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user