feat: Add opt-in telemetry and analytics system (VM-152) #141
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implement privacy-respecting telemetry to understand VoiceMode usage patterns. Core telemetry module (voice_mode/telemetry/): - collector.py: Gather stats from conversation logs with proper multi-exchange session tracking (uses conversation_id grouping) - privacy.py: Anonymization with duration/size binning, path sanitization - client.py: HTTP transmission with retry logic and offline queueing Configuration (voice_mode/config.py): - VOICEMODE_TELEMETRY: ask/true/false with normalization - DO_NOT_TRACK: Universal opt-out standard (overrides all) - Anonymous telemetry ID stored in ~/.voicemode/telemetry_id - Environment detection: OS, install method, MCP host, exec source Opt-in UX: - CLI prompt on first interactive use (voice_mode/cli.py) - MCP resources: voicemode://telemetry/status and /opt-in-prompt - MCP tools: telemetry_set_preference(), telemetry_check_status() Cloudflare Worker backend (cloudflare-worker/): - D1 database for event storage with 90-day retention - KV namespace for rate limiting (10/hour per ID, 100/hour per IP) - Payload validation, idempotency, IP hashing for privacy - Deployment docs (QUICK_START.md, DEPLOYMENT.md) Privacy protections: - Duration bins (<1min, 1-5min, 5-10min, 10-20min, 20-60min, >60min) - Exchange count bins (0, 1-5, 6-10, 11-20, >20) - Provider normalization (kokoro, whisper-local, openai) - No PII, audio content, or conversation text collected Documentation (docs/reference/environment.md): - Telemetry configuration variables - Three opt-out methods with precedence rules - What is/isn't collected - Privacy protections explained 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add sender.py module with maybe_send_telemetry_background() function - Hook telemetry send into server.py startup (non-blocking background thread) - Implement 24-hour cooldown between sends via last_send timestamp - Log sent payloads locally to ~/.voicemode/logs/telemetry/ for transparency - Auto-cleanup of telemetry logs older than 30 days - Fix collector.py to output 'os' instead of 'os_type' to match worker schema - Add sync-telemetry-local.sh script to export D1 database to local SQLite 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add period_start and period_end fields to telemetry payload - Collector now accepts start_date and end_date parameters - Sender uses last period_end as start for next collection - Fallback to timestamp field for older log entries without period_end - First send collects last 24 hours, subsequent sends from last period_end This ensures continuous telemetry coverage without gaps or overlaps, regardless of how often users start VoiceMode. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Users now only need to set VOICEMODE_TELEMETRY=true to enable telemetry. The endpoint URL defaults to the Cloudflare worker. Note: URL will be updated to a custom domain before release. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Remove separate last_send file and TELEMETRY_DIR constant - Use period_end from telemetry logs for both cooldown checking and continuous coverage - Simplifies architecture by using log files for dual purpose: transparency audit trail AND cooldown tracking 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
7 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
What's Included
Core Telemetry Module (
voice_mode/telemetry/)Configuration
VOICEMODE_TELEMETRY: ask/true/false with normalizationDO_NOT_TRACK: Universal opt-out standard (overrides all)~/.voicemode/telemetry_idOpt-in UX
voicemode://telemetry/statusand/opt-in-prompttelemetry_set_preference(),telemetry_check_status()Cloudflare Worker Backend (
cloudflare-worker/)Privacy Protections
Test plan
🤖 Generated with Claude Code