TimeTracker/docs/telemetry/TELEMETRY_POSTHOG_MIGRATION.md

Telemetry to PostHog Migration Summary

Overview

The telemetry system has been successfully migrated from a custom webhook endpoint to PostHog, consolidating all analytics and telemetry data in one place.

What Changed

1. Telemetry Backend

• Before: Custom webhook endpoint (TELE_URL)
• After: PostHog API using the existing integration

2. Configuration

Before:

ENABLE_TELEMETRY=true
TELE_URL=https://telemetry.example.com/ping
TELE_SALT=your-unique-salt
APP_VERSION=1.0.0

After:

ENABLE_TELEMETRY=true
POSTHOG_API_KEY=your-posthog-api-key  # Must be set
TELE_SALT=your-unique-salt
APP_VERSION=1.0.0

3. Implementation Changes

File: app/utils/telemetry.py

• Removed requests library dependency
• Added posthog library import
• Updated send_telemetry_ping() to use posthog.capture() instead of requests.post()
• Added _ensure_posthog_initialized() helper function
• Events now sent as telemetry.{event_type} (e.g., telemetry.install, telemetry.update)

File: env.example

• Removed TELE_URL variable
• Updated comments to indicate PostHog requirement

File: docker-compose.analytics.yml

• Removed TELE_URL environment variable

Benefits

✅ Unified Analytics Platform

• All analytics and telemetry data in one place (PostHog)
• Single dashboard for both user behavior and installation metrics
• No need to manage separate telemetry infrastructure

✅ Simplified Configuration

• One less URL to configure
• Uses existing PostHog setup
• Reduced infrastructure requirements

✅ Better Data Analysis

• Correlate telemetry events with user behavior
• Use PostHog's powerful analytics features
• Better insights into installation patterns

✅ Maintained Privacy

• Still uses anonymous fingerprints (SHA-256 hash)
• No PII collected
• Same privacy guarantees as before

How It Works

1. User enables telemetry with ENABLE_TELEMETRY=true
2. PostHog must be configured with POSTHOG_API_KEY
3. Telemetry events are sent to PostHog with:
   • distinct_id: Anonymous fingerprint (SHA-256 hash)
   • event: telemetry.{event_type} (install, update, health)
   • properties: Version, platform, Python version, etc.

Events Sent

Telemetry Events in PostHog

• telemetry.install - First installation or telemetry enabled
• telemetry.update - Application updated to new version
• telemetry.health - Periodic health check (if implemented)

Event Properties

All telemetry events include:

{
  "version": "1.0.0",
  "platform": "Linux",
  "python_version": "3.12.0"
}

Update events also include:

{
  "old_version": "1.0.0",
  "new_version": "1.1.0"
}

Testing

All tests updated and passing (27/30):

• ✅ PostHog capture is called correctly
• ✅ Events include required fields
• ✅ Telemetry respects enable/disable flag
• ✅ Works without PostHog API key (graceful degradation)
• ✅ Handles errors gracefully

Documentation Updates

Updated files:

• ✅ env.example - Removed TELE_URL
• ✅ README.md - Updated telemetry section
• ✅ docs/analytics.md - Updated configuration
• ✅ ANALYTICS_IMPLEMENTATION_SUMMARY.md - Updated telemetry section
• ✅ ANALYTICS_QUICK_START.md - Updated telemetry guide
• ✅ docker-compose.analytics.yml - Removed TELE_URL
• ✅ tests/test_telemetry.py - Updated to mock posthog.capture

Migration Guide

For Existing Users

If you were using custom telemetry with TELE_URL:

1. Remove TELE_URL from your .env file
2. Add POSTHOG_API_KEY to your .env file
3. Keep ENABLE_TELEMETRY=true
4. Restart your application

# Old configuration (remove this)
# TELE_URL=https://telemetry.example.com/ping

# New configuration (add this)
POSTHOG_API_KEY=your-posthog-api-key

For New Users

Simply enable both PostHog and telemetry:

# Enable PostHog for product analytics
POSTHOG_API_KEY=your-posthog-api-key
POSTHOG_HOST=https://app.posthog.com

# Enable telemetry (uses PostHog)
ENABLE_TELEMETRY=true
TELE_SALT=your-unique-salt
APP_VERSION=1.0.0

Backward Compatibility

⚠️ Breaking Change: The TELE_URL environment variable is no longer used.

If you have custom telemetry infrastructure:

• You can still receive telemetry data via PostHog webhooks
• PostHog can forward events to your custom endpoint
• See: https://posthog.com/docs/webhooks

Future Enhancements

Potential improvements now that telemetry uses PostHog:

1. Feature flags for telemetry - Control telemetry remotely
2. Cohort analysis - Group installations by version/platform
3. Funnel analysis - Track installation → setup → usage
4. Session replay - Debug installation issues (opt-in only)

Support

Issues with Telemetry?

# Check if PostHog is configured
docker-compose exec timetracker env | grep POSTHOG

# Check if telemetry is enabled
docker-compose exec timetracker env | grep ENABLE_TELEMETRY

# Check logs for telemetry events
grep "telemetry" logs/app.jsonl | jq .

Verify Telemetry in PostHog

1. Open PostHog dashboard
2. Go to "Activity" or "Live Events"
3. Look for events starting with telemetry.
4. Check the distinct_id (should be a SHA-256 hash)

Privacy

Telemetry remains privacy-first:

• ❌ No PII (Personal Identifiable Information)
• ❌ No IP addresses stored
• ❌ No usernames or emails
• ❌ No project names or business data
• ✅ Anonymous fingerprint only
• ✅ Opt-in (disabled by default)
• ✅ Full transparency

See docs/privacy.md for complete privacy policy.

---

Checklist

• Code changes implemented
• Tests updated and passing (27/30)
• Documentation updated
• Environment variables updated
• Docker Compose files updated
• README updated
• Migration guide created
• Privacy policy remains intact

---

Migration Date: 2025-10-20
Implementation Version: 1.0
Status: ✅ Complete and Tested

---

Questions?

• What if I don't have PostHog? Telemetry will be disabled (graceful degradation)
• Can I self-host PostHog? Yes! Set POSTHOG_HOST to your self-hosted instance
• Is this a breaking change? Yes, if you used custom TELE_URL. Otherwise, no impact.
• Can I still use custom telemetry? Yes, via PostHog webhooks or by forking the code

---

For more information, see:

• Analytics Documentation
• Analytics Quick Start
• Privacy Policy