Skip to content

analytics.md

Latest commit

 

History

History
59 lines (44 loc) · 2.3 KB

analytics.md

File metadata and controls

59 lines (44 loc) · 2.3 KB
Raw

Analytics and Monitoring

TimeTracker provides privacy-aware analytics and monitoring with Grafana Cloud OTLP as the telemetry sink.

Overview

  1. Structured JSON Logging - Application event logs in logs/app.jsonl
  2. Sentry Integration - Error monitoring and tracing (optional)
  3. Prometheus Metrics - Runtime metrics at /metrics
  4. Grafana OTLP Telemetry - Installation + product analytics telemetry

Telemetry Model

Base telemetry (anonymous, default behavior)

  • Installation-level telemetry (base_telemetry.first_seen, base_telemetry.heartbeat)
  • Includes install UUID, app version, platform, OS, architecture, locale, timezone
  • No direct PII fields

Detailed analytics (explicit opt-in only)

  • Product events such as timer.started, project.created, auth.login
  • Sent only when admins enable detailed analytics in the app
  • PII-filtered before export
  • Support UI funnel events (support.modal_opened, support.donation_clicked, etc.) are emitted the same way when opt-in is enabled; see all_tracked_events.md.

Configuration

# Grafana OTLP sink
GRAFANA_OTLP_ENDPOINT=https://otlp-gateway-.../otlp/v1/logs
GRAFANA_OTLP_TOKEN=your-token

# Detailed analytics consent switch (app-controlled per installation)
ENABLE_TELEMETRY=true

# Optional error monitoring
SENTRY_DSN=
SENTRY_TRACES_RATE=0.1

# Support / checkout links (optional; defaults in app/config.py)
SUPPORT_PURCHASE_URL=https://timetracker.drytrix.com/support.html
SUPPORT_PORTAL_BASE=https://timetracker.drytrix.com
# Optional one line shown in the support modal when set
SUPPORT_SOCIAL_PROOF_TEXT=
# Optional per-tier donate URLs (default to SUPPORT_PURCHASE_URL when unset)
SUPPORT_DONATE_EUR5_URL=
SUPPORT_DONATE_EUR10_URL=
SUPPORT_DONATE_EUR25_URL=
# Long-session soft prompt threshold in minutes (default 120)
SUPPORT_LONG_SESSION_MINUTES=120

Per-user report generation counts for the support modal are stored in users.support_stats_reports_generated (see migration 149_add_user_support_stats_reports_generated).

Troubleshooting

  • If no telemetry arrives, verify GRAFANA_OTLP_ENDPOINT and GRAFANA_OTLP_TOKEN
  • If detailed events are missing, confirm detailed analytics is enabled in admin settings
  • If only base events appear, consent is likely disabled (expected behavior)