# Epic: Observability / Metrics / Gamification

## DESCRIPTION
Comprehensive metrics collection, cost tracking, performance monitoring, and gamification to make LLMHosts indispensable and sticky. The savings ticker and gamification are core to viral growth.

**POST-PIVOT (2026-02-14)**: Elevated request metrics and cost savings to Phase 1 P0 (critical for the "holy shit" moment). Gamification stays Phase 3.

## BACKLOG ITEMS

### OBS-001: Request Metrics Collection
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Collect per-request metrics: latency, tokens, cost, model used, cache hit/miss, routing decision, backend type (local/cloud/hive). Store in local SQLite.
- **Acceptance**: Every request has complete metrics recorded and queryable. Feeds into dashboard.
- **Dependencies**: CB-003, CB-012

### OBS-002: Cost Savings Calculator
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Calculate savings: (what cloud would cost) - (actual cost with local + caching). Running total since install.
- **Acceptance**: Accurate running total. Updated per-request. Visible in TUI and web dashboard.
- **Dependencies**: OBS-001

### OBS-003: Per-Model Performance Tracking
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Track quality (feedback), latency, cost per model over time. Show users which models perform best for their use cases.
- **Acceptance**: Users see model comparison: "Llama 3.2 is 40% faster for code but Claude is better for research."
- **Dependencies**: OBS-001, FE-009 (feedback)

### OBS-004: Hardware Utilization Metrics
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: GPU/CPU/memory utilization per node, historical trends.
- **Acceptance**: Users see when hardware is idle vs busy. Informs model loading decisions.
- **Dependencies**: CF-002, CF-006

### OBS-005: Savings Milestones & Progress Bars
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Visual progress toward savings goals ($100, $500, $1000 saved). Celebration notifications.
- **Acceptance**: Progress bars fill as users save. "You just saved $100!" notification.
- **Dependencies**: OBS-002

### OBS-006: Achievement Badges
- **Priority**: P2
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Gamification badges: "First 1000 local inferences," "90% cache hit rate," "Week of savings," etc.
- **Acceptance**: Users earn and display achievements. Creates engagement loop.
- **Dependencies**: OBS-001

### OBS-007: Efficiency Streaks
- **Priority**: P2
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Track consecutive days meeting cost/efficiency targets. Streak counter.
- **Acceptance**: Users see streak counter. Motivated to maintain efficient usage.
- **Dependencies**: OBS-002

### OBS-008: Toil Reduction Score
- **Priority**: P2
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Quantified metric of complexity eliminated (routing decisions made, models managed, cache hits served).
- **Acceptance**: Single score representing complexity LLMHosts handles. Visible in dashboard.
- **Dependencies**: OBS-001

### OBS-009: Platform Monitoring (Prometheus/Grafana)
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Monitoring stack for production: service health, inference latency, error rates, node connectivity. Alerting for downtime.
- **Acceptance**: Dashboard shows all service health. Alerts fire within 60s of issue.
- **Dependencies**: Docker infrastructure
