Back to PXL-808
PXL-808Documentation
Session Logging System - Technical Design Document
For task: 📱 Track sessions on device with cloud sync
Debugging sync race conditions (PXL-801) and other issues is extremely difficult with live logs because:
- ●Issues are intermittent and hard to reproduce
- ●By the time an issue is noticed, the relevant logs have scrolled away
- ●No way to capture logs from real-world usage sessions
- ●Can't debug issues that happen when not connected to Xcode
Create an on-device session logging system that:
- ●Captures all console output to a local log file per app session
- ●Syncs logs to CloudKit public database for cross-device access
- ●Tracks session status (active/terminated/crashed)
- ●Provides UI for viewing and exporting logs
- ●Auto-cleans old logs (7 days local, 30 days remote)
┌─────────────────────────────────────────────────────────────────────────────┐
│ APP LAUNCH │
│ │ │
│ ┌────────────────────────┼────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │
│ │ Create new │ │ Check for previous │ │ Cleanup remote │ │
│ │ session log │ │ incomplete sessions │ │ logs > 30 days │ │
│ │ (local) │ │ (crashed last time?) │ │ for this user │ │
│ └─────────────┘ └──────────┬───────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Upload unsynced prev │ │
│ │ session as "CRASHED" │ │
│ └──────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ APP RUNNING │
│ │ │
│ ┌────────────────────────┴────────────────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Log to file │ │ Every 60 seconds: │ │
│ │ continuously │ │ Upload to CloudKit │ │
│ │ (local) │ │ status: "ACTIVE" │ │
│ └─────────────────┘ └─────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ APP STATE CHANGES │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ BACKGROUNDED │ │ FOREGROUNDED │ │ TERMINATED │ │
│ │ • Flush buffer │ │ • Log "resumed"│ │ • Mark TERMINATED │ │
│ │ • Keep logging │ │ • Upload to CK │ │ • Final flush │ │
│ │ │ │ immediately │ │ • Upload to CK │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ APP CRASH │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ ❌ No time to handle during crash │ │
│ │ │ │
│ │ ✅ On NEXT launch: │ │
│ │ • Detect incomplete session │ │
│ │ (no SESSION END marker) │ │
│ │ • Upload with status: "CRASHED" │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Record Type: SessionLog │
│ Database: Public (developer-accessible from any device) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Fields: │
│ ┌───────────────────┬─────────────┬──────────────────────────┐│
│ │ Field │ Type │ Example ││
│ ├───────────────────┼─────────────┼──────────────────────────┤│
│ │ userId │ String │ "abc123-def456-..." ││
│ │ cloudKitUserId │ String │ "_abc123xyz..." ││
│ │ sessionId │ String │ "2025-12-30_14-32-05" ││
│ │ filename │ String │ "abc123_session_..." ││
│ │ logFile │ CKAsset │ (the .log file) ││
│ │ status │ String │ "active"/"terminated"/ ││
│ │ │ │ "crashed" ││
│ │ startedAt │ Date │ 2025-12-30T14:32:05Z ││
│ │ lastUpdatedAt │ Date │ 2025-12-30T15:45:00Z ││
│ │ endedAt │ Date? │ null (if active) ││
│ │ deviceModel │ String │ "iPhone 15 Pro" ││
│ │ iosVersion │ String │ "18.2" ││
│ │ appVersion │ String │ "1.2.3 (456)" ││
│ │ fileSizeBytes │ Int64 │ 1048576 ││
│ └───────────────────┴─────────────┴──────────────────────────┘│
│ │
│ Record ID: {userId}_{sessionId} │
│ (allows upsert on each upload) │
│ │
└─────────────────────────────────────────────────────────────────┘
================================================================================
SESSION: {userId}_{sessionId}
STATUS: ACTIVE
LAST UPDATED: 2025-12-30 15:45:00.123
================================================================================
Device: iPhone 15 Pro
iOS: 18.2
App: NutriKit 1.2.3 (456)
User ID: abc123-def456-...
CloudKit ID: _abc123xyz...
================================================================================
[14:32:05.001] [INFO] [App] 📱 Session started
[14:32:05.045] [INFO] [Sync] Starting full sync...
[14:35:20.234] [INFO] [MealCreate] New meal: "Breakfast"
[14:40:05.567] [INFO] [App] ⏸️ Entering background
[15:15:30.001] [INFO] [App] ▶️ Returning to foreground
[15:15:30.002] [INFO] [App] ☁️ Uploading log to CloudKit...
[15:20:45.123] [INFO] [MealCreate] New meal: "Lunch"
...
================================================================================
SESSION END: 2025-12-30 18:45:12.789
STATUS: TERMINATED
DURATION: 4h 13m 7s
================================================================================
Admin Sheet (existing, with new row)
┌─────────────────────────────────────────────┐
│ ← Admin │
├─────────────────────────────────────────────┤
│ │
│ DATA MANAGEMENT │
│ ┌─────────────────────────────────────┐ │
│ │ 🔄 Restore Meals from Backup > │ │
│ ├─────────────────────────────────────┤ │
│ │ 🎲 Generate Dummy Data > │ │
│ ├─────────────────────────────────────┤ │
│ │ 🗑️ Delete Data > │ │
│ └─────────────────────────────────────┘ │
│ │
│ DIAGNOSTICS │
│ ┌─────────────────────────────────────┐ │
│ │ 📋 Session Logs > │ │
│ │ 12 sessions • 2.4 MB │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────┘
Session Logs List View
┌─────────────────────────────────────────────┐
│ ← Session Logs Edit │
├─────────────────────────────────────────────┤
│ │
│ [Local ▼] [Cloud] ← Segment picker │
│ │
│ 🟢 CURRENT SESSION (this device) │
│ ┌─────────────────────────────────────┐ │
│ │ 📱 iPhone 15 Pro > │ │
│ │ Today, 2:32 PM • Running • 1.8 MB │ │
│ │ ☁️ Last synced: 2 min ago │ │
│ └─────────────────────────────────────┘ │
│ │
│ CLOUD SESSIONS (all devices, 30 days) │
│ ┌─────────────────────────────────────┐ │
│ │ 📱 iPhone 15 Pro ACTIVE > │ │
│ │ Today, 2:32 PM • 1.8 MB │ │
│ ├─────────────────────────────────────┤ │
│ │ 📱 iPhone 15 Pro TERMINATED> │ │
│ │ Yesterday, 8:30 AM • 3.2 MB │ │
│ ├─────────────────────────────────────┤ │
│ │ 💻 iPad Pro TERMINATED> │ │
│ │ Dec 28, 10:15 AM • 2.1 MB │ │
│ ├─────────────────────────────────────┤ │
│ │ 📱 iPhone 15 Pro CRASHED > │ │
│ │ Dec 27, 3:45 PM • 1.5 MB │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 🗑️ Delete All Cloud Logs │ │
│ └─────────────────────────────────────┘ │
│ │
│ Cloud logs auto-delete after 30 days │
│ │
└─────────────────────────────────────────────┘
Log Detail View
┌─────────────────────────────────────────────┐
│ ← Yesterday, 8:30 AM ↗ Share │
├─────────────────────────────────────────────┤
│ │
│ SESSION INFO │
│ ┌─────────────────────────────────────┐ │
│ │ Started Dec 29, 8:30:15 AM │ │
│ │ Ended Dec 29, 10:52:30 PM │ │
│ │ Duration 14h 22m 15s │ │
│ │ File Size 3.2 MB │ │
│ │ Device iPhone 15 Pro │ │
│ │ iOS 18.2 │ │
│ │ App Ver 1.2.3 (456) │ │
│ └─────────────────────────────────────┘ │
│ │
│ LOG CONTENT [Search 🔍] │
│ ┌─────────────────────────────────────┐ │
│ │ [08:30:15] 📱 Session started │ │
│ │ [08:30:16] [Sync] Starting... │ │
│ │ [08:35:20] [MealCreate] Breakfast │ │
│ │ [08:40:05] ⏸️ Entering background │ │
│ │ [12:15:30] ▶️ Returning foreground │ │
│ │ [12:15:32] [Sync] Starting... │ │
│ │ [12:20:45] [MealCreate] Lunch │ │
│ │ [12:25:10] ⏸️ Entering background │ │
│ │ [18:30:00] ▶️ Returning foreground │ │
│ │ [18:35:22] [MealCreate] Dinner │ │
│ │ [18:40:15] ⏸️ Entering background │ │
│ │ [22:52:30] 🛑 Session terminated │ │
│ │ ▼ scroll │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 📤 Export Log File │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────┘
Time Event Local CloudKit
─────────────────────────────────────────────────────────────────────
14:32 App launches 📄 Created
14:32 Session starts ✍️ Writing
14:33 +60 sec timer fires ✍️ Writing ☁️ Upload (ACTIVE)
14:34 +60 sec timer fires ✍️ Writing ☁️ Upload (ACTIVE)
14:35 User backgrounds app ✍️ Flush
14:40 User foregrounds ✍️ Writing ☁️ Upload (ACTIVE)
14:41 +60 sec timer fires ✍️ Writing ☁️ Upload (ACTIVE)
...
18:45 User terminates app 📄 Complete ☁️ Upload (TERMINATED)
─────────────────────────────────────────────────────────────────────
CRASH SCENARIO:
14:32 App launches 📄 Created
14:33 +60 sec timer fires ✍️ Writing ☁️ Upload (ACTIVE)
14:34 💥 CRASH 📄 Incomplete ☁️ Still "ACTIVE"
(next launch)
14:40 App launches 📄 Detect orphan ☁️ Upload (CRASHED)
Per-Session Size Analysis
| Log Verbosity | Lines/Hour | Bytes/Line | Size/Hour | 8hr Session |
|---|---|---|---|---|
| Light use | ~500 | ~100 | ~50 KB | ~400 KB |
| Normal use | ~2,000 | ~120 | ~240 KB | ~2 MB |
| Heavy use | ~5,000 | ~150 | ~750 KB | ~6 MB |
| Debug sync | ~10,000 | ~150 | ~1.5 MB | ~12 MB |
Realistic estimate: 2-4 MB per session (normal use)
30-Day Storage per User
| Usage Pattern | Sessions/Day | Size/Session | 30-Day Total |
|---|---|---|---|
| Casual | 1 | 2 MB | ~60 MB |
| Regular | 1-2 | 3 MB | ~120 MB |
| Power user | 2-3 | 4 MB | ~300 MB |
| Debug mode | 2-3 | 10 MB | ~900 MB |
Typical user: ~100-200 MB per 30 days
CloudKit Public Database Capacity
With 1 PB total storage:
- ●1 user: 200 MB = 0.00002% of capacity
- ●100 users: 20 GB = 0.002% of capacity
- ●1,000 users: 200 GB = 0.02% of capacity
- ●10,000 users: 2 TB = 0.2% of capacity
- ●100,000 users: 20 TB = 2% of capacity
Verdict: Storage is not a concern with 1 PB capacity and 30-day cleanup
Documents/
└── Logs/
├── session_2025-12-30_14-32-05.log ← Current (in progress)
├── session_2025-12-30_10-15-32.log ← 312 KB
├── session_2025-12-29_20-30-15.log ← 1.2 MB
├── session_2025-12-29_12-45-00.log ← 245 KB
└── session_2025-12-28_15-20-30.log ← 567 KB
(Auto-cleanup: files older than 7 days deleted on app launch)
- ●
Packages/App/Sources/App/Services/SessionLogger.swift- ●Core logging service with stdout/stderr capture
- ●File creation at Documents/Logs/
- ●Timestamp formatting
- ●Session header/footer writing
- ●Flush mechanism
- ●
Packages/App/Sources/App/Services/SessionLogCloudKitManager.swift- ●CloudKit sync with public database
- ●Upload/fetch/delete operations
- ●Crash detection logic
- ●
NutriKit/Views/Debug/SessionLogsView.swift- ●List view with Local/Cloud segments
- ●Session rows with status badges
- ●
NutriKit/Views/Debug/SessionLogDetailView.swift- ●Detail view with session info
- ●Scrollable log content
- ●Search and export functionality
- ●
NutriKit/NutriKitApp.swift- ●Initialize SessionLogger on launch
- ●Handle scene phase changes
- ●Register for termination notification
- ●
NutriKit/Views/Debug/AdminSheet.swift- ●Add "DIAGNOSTICS" section
- ●Add "Session Logs" navigation row
- ●
Packages/App/Sources/App/Extensions/Logger.swift- ●Integrate OSLog with session file writing
- ●Session continues through backgrounding, only ends on true termination
- ●Crash detection relies on missing SESSION END marker
- ●CloudKit uploads use CKAsset for efficient large file handling
- ●60-second upload interval balances freshness vs. battery/network
- ●Public database allows developer access from any device
- ●Buffer flush on background ensures no data loss if iOS kills app
Created Dec 30, 2025, 1:33 PM · Updated Dec 30, 2025, 1:36 PM