TimeTracker/docs/TELEMETRY_QUICK_START.md

Telemetry & Analytics Quick Start Guide

For End Users

First-Time Setup

When you first access TimeTracker, you'll see a welcome screen asking about telemetry:

1. Read the Privacy Information - Review what data is collected (and what isn't)
2. Choose Your Preference:
   • ✅ Enable Telemetry - Help improve TimeTracker by sharing anonymous usage data
   • ⬜ Disable Telemetry - No data will be sent (default)
3. Click "Complete Setup & Continue"

You can change this decision anytime in the admin settings.

Viewing Telemetry Status (Admin Only)

1. Login as an administrator
2. Go to Admin → Telemetry Dashboard (or visit /admin/telemetry)
3. View:
   • Current telemetry status (enabled/disabled)
   • Installation ID and fingerprint
   • PostHog configuration status
   • Sentry configuration status
   • What data is being collected

Changing Telemetry Preference (Admin Only)

1. Go to /admin/telemetry
2. Click "Enable Telemetry" or "Disable Telemetry" button
3. Your preference is saved immediately

For Administrators

Setting Up Analytics Services

PostHog (Product Analytics)

To enable PostHog tracking:

1. Sign up for PostHog at https://posthog.com (or self-host)
2. Get your API key from PostHog dashboard
3. Set environment variable:

   export POSTHOG_API_KEY="your-api-key-here"
   export POSTHOG_HOST="https://app.posthog.com"  # Default, change if self-hosting
   

4. Restart the application
5. Enable telemetry in admin dashboard (if not already enabled)

Sentry (Error Monitoring)

To enable Sentry error tracking:

1. Sign up for Sentry at https://sentry.io (or self-host)
2. Create a project and get your DSN
3. Set environment variable:

   export SENTRY_DSN="your-sentry-dsn-here"
   export SENTRY_TRACES_RATE="0.1"  # Sample 10% of requests
   

4. Restart the application

Installation-Specific Configuration

TimeTracker automatically generates a unique salt and installation ID on first startup. These are stored in data/installation.json and persist across restarts.

File location: data/installation.json

Example content:

{
  "telemetry_salt": "8f4a7b2e9c1d6f3a5e8b4c7d2a9f6e3b1c8d5a7f2e9b4c6d3a8f5e1b7c4d9a2f",
  "installation_id": "a3f5c8e2b9d4a1f7",
  "setup_complete": true,
  "telemetry_enabled": false,
  "setup_completed_at": "2025-10-20T12:34:56.789"
}

Important:

• ⚠️ Do not delete this file unless you want to reset the setup
• ⚠️ Back up this file with your database backups
• ⚠️ Keep the salt secure (though it doesn't contain PII)

Viewing Tracked Events

If telemetry is enabled, all events are logged to logs/app.jsonl:

tail -f logs/app.jsonl | grep "event_type"

Example event:

{
  "timestamp": "2025-10-20T12:34:56.789Z",
  "level": "info",
  "event_type": "timer.started",
  "user_id": 1,
  "entry_id": 42,
  "project_id": 7
}

Docker Deployment

The Docker Compose configuration includes all analytics services:

# Start all services (including analytics)
docker-compose up -d

# View logs for analytics services
docker-compose logs -f prometheus grafana loki

Services included:

• Prometheus - Metrics collection (http://localhost:9090)
• Grafana - Visualization (http://localhost:3000)
• Loki - Log aggregation
• Promtail - Log shipping

Privacy & Compliance

GDPR Compliance

TimeTracker's telemetry system is designed with GDPR principles in mind:

• ✅ Consent-Based: Opt-in by default
• ✅ Transparent: Clear documentation of collected data
• ✅ Right to Withdraw: Can disable anytime
• ✅ Data Minimization: Only collects necessary event data
• ✅ No PII: Never collects personally identifiable information

Data Retention

• JSON Logs: Rotate daily, keep 30 days (configurable)
• PostHog: Follow PostHog's retention policy
• Sentry: Follow Sentry's retention policy
• Prometheus: 15 days default (configurable in prometheus/prometheus.yml)

Disabling All Telemetry

To completely disable all telemetry and analytics:

1. In Application: Disable in /admin/telemetry
2. Remove API Keys:

   unset POSTHOG_API_KEY
   unset SENTRY_DSN
   unset ENABLE_TELEMETRY
   

3. Restart Application

Troubleshooting

Setup Page Keeps Appearing

If the setup page keeps appearing after completion:

1. Check data/installation.json exists and has "setup_complete": true
2. Check file permissions (application must be able to write to data/ directory)
3. Check logs for errors: tail -f logs/app.jsonl

Events Not Appearing in PostHog

1. Check API Key: Verify POSTHOG_API_KEY is set
2. Check Telemetry Status: Go to /admin/telemetry and verify it's enabled
3. Check Logs: tail -f logs/app.jsonl | grep PostHog
4. Check Network: Ensure server can reach PostHog host

Admin Dashboard Not Accessible

1. Login as Admin: Only administrators can access /admin/telemetry
2. Check User Role: Verify user has is_admin=True in database
3. Check Logs: Look for permission errors in logs

Support & Documentation

• Full Documentation: See docs/analytics.md
• All Tracked Events: See docs/all_tracked_events.md
• Privacy Policy: See docs/privacy.md
• GitHub Issues: Report bugs or request features

FAQ

Q: Is telemetry required to use TimeTracker? A: No! Telemetry is completely optional and disabled by default.

Q: Can you identify me from the telemetry data? A: No. We only collect anonymous event types and numeric IDs. No usernames, emails, or project names are ever collected.

Q: How do I know what's being sent? A: Check the /admin/telemetry dashboard and review docs/all_tracked_events.md for a complete list.

Q: Can I use my own PostHog/Sentry instance? A: Yes! Set POSTHOG_HOST and SENTRY_DSN to your self-hosted instances.

Q: What happens to my data if I disable telemetry? A: Nothing is sent to external services. Events are still logged locally in logs/app.jsonl for debugging.

Q: Can I re-run the setup? A: Yes, delete data/installation.json and restart the application.