TimeTracker/docs/analytics.md

Analytics and Monitoring

TimeTracker includes comprehensive analytics and monitoring capabilities to help understand application usage, performance, and errors.

Overview

The analytics system consists of several components:

1. Structured JSON Logging - Application-wide event logging in JSON format
2. Sentry Integration - Error monitoring and performance tracking
3. Prometheus Metrics - Performance metrics and monitoring
4. PostHog Analytics - Product analytics and user behavior tracking
5. Telemetry - Opt-in installation and version tracking

Features

Structured Logging

All application events are logged in structured JSON format to logs/app.jsonl. Each log entry includes:

• Timestamp
• Log level
• Event name
• Request ID (for tracing requests)
• Additional context (user ID, project ID, etc.)

Example log entry:

{
  "asctime": "2025-10-20T10:30:45.123Z",
  "levelname": "INFO",
  "name": "timetracker",
  "message": "project.created",
  "request_id": "abc123-def456",
  "user_id": 42,
  "project_id": 15
}

Error Monitoring (Sentry)

When enabled, Sentry captures:

• Uncaught exceptions
• Performance traces
• Request context
• User context

Performance Metrics (Prometheus)

Exposed at /metrics endpoint:

• Total request count by method, endpoint, and status code
• Request latency histogram by endpoint
• Custom business metrics

Product Analytics (PostHog)

Tracks user behavior and feature usage with advanced features:

• Event Tracking: Timer operations, project management, reports, exports
• Person Properties: User role, auth method, login history
• Feature Flags: Gradual rollouts, A/B testing, kill switches
• Group Analytics: Segment by platform, version, deployment method
• Cohort Analysis: Target specific user segments
• Rich Context: Browser, device, URL, environment on every event

See POSTHOG_ADVANCED_FEATURES.md for complete guide.

Telemetry

Optional, opt-in telemetry helps us understand:

• Number of active installations (anonymized)
• Version distribution
• Update patterns

Privacy: Telemetry is disabled by default and contains no personally identifiable information (PII).

Implementation: Telemetry data is sent via PostHog using anonymous fingerprints, keeping all installation data in one place.

Configuration

All analytics features are controlled via environment variables. See env.example for configuration options.

Enabling Analytics

# Enable Sentry
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_TRACES_RATE=0.1  # 10% sampling for performance traces

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

# Enable Telemetry (opt-in, uses PostHog)
ENABLE_TELEMETRY=true
TELE_SALT=your-unique-salt
APP_VERSION=1.0.0

Disabling Analytics

By default, most analytics features are disabled. To ensure they remain disabled:

# Disable all optional analytics
SENTRY_DSN=
POSTHOG_API_KEY=
ENABLE_TELEMETRY=false

Structured logging to files is always enabled as it's essential for troubleshooting.

Log Management

Logs are written to logs/app.jsonl and should be rotated using:

• Docker volume mounts + host logrotate
• Grafana Loki + Promtail
• Elasticsearch + Filebeat
• Or similar log aggregation solutions

Dashboards

Recommended dashboards:

Sentry

• Error rate alerts
• New issue notifications
• Performance regression alerts

Grafana + Prometheus

• Request rate and latency (P50, P95, P99)
• Error rates by endpoint
• Active timers gauge
• Database connection pool metrics

PostHog

• User engagement funnels
• Feature adoption rates
• Session recordings (if enabled)

Data Retention

• Logs: Retained locally based on your logrotate configuration
• Sentry: Based on your Sentry plan (typically 90 days)
• Prometheus: Based on your Prometheus configuration (typically 15-30 days)
• PostHog: Based on your PostHog plan
• Telemetry: 12 months

Privacy & Compliance

See privacy.md for detailed information about data collection, retention, and GDPR compliance.

Event Schema

See events.md for a complete list of tracked events and their properties.

Maintenance

Adding New Events

1. Define the event in docs/events.md
2. Instrument the code using log_event() or track_event()
3. Update this documentation
4. Test in development environment
5. Monitor in production dashboards

Event Naming Convention

• Use dot notation: resource.action
• Examples: project.created, timer.started, export.csv
• Be consistent with existing event names

Who Can Add Events

Changes to analytics require approval from:

• Product owner (for PostHog events)
• DevOps/SRE (for infrastructure metrics)
• Privacy officer (for any data collection changes)

Troubleshooting

Logs Not Appearing

1. Check logs/ directory permissions
2. Verify LOG_LEVEL is set correctly
3. Check disk space

Sentry Not Receiving Errors

1. Verify SENTRY_DSN is set correctly
2. Check network connectivity
3. Verify Sentry project is active
4. Check Sentry rate limits

Prometheus Metrics Not Available

1. Verify /metrics endpoint is accessible
2. Check Prometheus scrape configuration
3. Verify network connectivity

PostHog Events Not Appearing

1. Verify POSTHOG_API_KEY is set correctly
2. Check PostHog project settings
3. Verify network connectivity
4. Check PostHog rate limits

Support

For analytics-related issues:

1. Check this documentation
2. Review logs in logs/app.jsonl
3. Check service-specific dashboards (Sentry, Grafana, PostHog)
4. Contact support with relevant log excerpts