TimeTracker/docs/TELEMETRY_QUICK_START.md

Telemetry & Analytics Quick Start Guide

For End Users

First-Time Setup (Guided Wizard)

When you first access TimeTracker, you'll see a guided setup wizard (6 steps). You can configure the basics in one flow, then continue to the dashboard.

1. Welcome – Intro; click Next to start.
2. Region & time – Timezone, date format, time format, and currency (used for reports and invoices).
3. Company – Company name, address, email; optional phone and website (for invoices and branding).
4. System – Allow self-registration, time rounding, single active timer per user, idle timeout (minutes).
5. Integrations (optional) – Google Calendar OAuth (Client ID / Secret). You can skip this and configure later in Admin → Settings.
6. Privacy & finish – Choose whether to enable detailed analytics:
   • ✅ Enable detailed analytics – Send richer product usage diagnostics
   • ⬜ Disable detailed analytics – Only anonymous base telemetry will be sent (default)
   • Click Complete Setup & Continue to finish.

You can change telemetry and all other options anytime in 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
   • Grafana OTLP 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

Grafana Cloud OTLP (Telemetry Sink)

To enable telemetry export:

1. Set your OTLP endpoint and token:

   export GRAFANA_OTLP_ENDPOINT="https://otlp-gateway-.../otlp/v1/logs"
   export GRAFANA_OTLP_TOKEN="your-token-here"
   

2. Restart the application
3. In Admin, choose whether detailed analytics should be 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)
• Grafana OTLP sink: Follow your Grafana Cloud 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 GRAFANA_OTLP_ENDPOINT
   unset GRAFANA_OTLP_TOKEN
   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 Grafana

1. Check OTLP config: Verify GRAFANA_OTLP_ENDPOINT and GRAFANA_OTLP_TOKEN are set
2. Check Telemetry Status: Go to /admin/telemetry and verify it's enabled
3. Check Logs: tail -f logs/app.jsonl | grep telemetry
4. Check Network: Ensure server can reach OTLP endpoint

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 Grafana/Sentry instance? A: Yes. Configure your own OTLP endpoint/token and Sentry DSN.

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.