daily-notification-plugin/docs/testing/IOS_LOGGING_GUIDE.md

iOS Logging Guide - How to Check Logs for Errors

Purpose: Quick reference for viewing iOS app logs during development and debugging

Last Updated: 2025-11-15
Status: 🎯 ACTIVE - Reference guide for iOS debugging

---

Quick Start

Most Common Methods (in order of ease):

1. Xcode Console (when app is running in Xcode) - Easiest
2. Console.app (macOS system console) - Good for background logs
3. Command-line (xcrun simctl) - Best for automation/scripts

---

Method 1: Xcode Console (Recommended for Development)

When to use: App is running in Xcode (simulator or device)

Steps:

1. Open Xcode and run your app (Cmd+R)
2. Open Debug Area:
   • Press Cmd+Shift+Y (or View → Debug Area → Activate Console)
   • Or click the bottom panel icon in Xcode
3. Filter logs:
   • Click the search box at bottom of console
   • Type: DNP- or DailyNotification or Error
   • Press Enter

Filter Examples:

DNP-PLUGIN    # Plugin operations
DNP-FETCH     # Background fetch operations
DNP-SCHEDULER # Scheduling operations
DNP-STORAGE   # Storage operations
Error         # All errors

Copy-Paste Commands (LLDB Console):

When app is running, you can also use LLDB commands in Xcode console:

// Check pending notifications
po UNUserNotificationCenter.current().pendingNotificationRequests()

// Check permission status
po await UNUserNotificationCenter.current().notificationSettings()

// Manually trigger BGTask (simulator only)
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]

---

Method 2: Console.app (macOS System Console)

When to use: App is running in background, or you want to see system-level logs

Steps:

1. Open Console.app:

   • Press Cmd+Space (Spotlight)
   • Type: Console
   • Press Enter
   • Or: Applications → Utilities → Console

2. Select Device/Simulator:

   • In left sidebar, expand "Devices"
   • Select your simulator or connected device
   • Or select "All Logs" for system-wide logs

3. Filter logs:

   • Click search box (top right)
   • Type: DNP- or com.timesafari.dailynotification
   • Press Enter

Filter by Subsystem (Structured Logging):

The plugin uses structured logging with subsystems:

com.timesafari.dailynotification.plugin    # Plugin operations
com.timesafari.dailynotification.fetch    # Fetch operations
com.timesafari.dailynotification.scheduler # Scheduling operations
com.timesafari.dailynotification.storage    # Storage operations

To filter by subsystem:

• In Console.app search: subsystem:com.timesafari.dailynotification

---

Method 3: Command-Line (xcrun simctl)

When to use: Automation, scripts, or when Xcode/Console.app aren't available

Stream Live Logs (Simulator):

# Stream all logs from booted simulator
xcrun simctl spawn booted log stream

# Stream only plugin logs (filtered)
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.timesafari.dailynotification"'

# Stream with DNP- prefix filter
xcrun simctl spawn booted log stream | grep "DNP-"

Save Logs to File:

# Save all logs to file
xcrun simctl spawn booted log stream > device.log 2>&1

# Save filtered logs
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.timesafari.dailynotification"' > plugin.log 2>&1

# Then analyze with grep
grep -E "\[DNP-(FETCH|SCHEDULER|PLUGIN)\]" device.log

View Recent Logs (Not Streaming):

# Show recent logs (last 100 lines)
xcrun simctl spawn booted log show --last 1m | grep "DNP-"

# Show logs for specific time range
xcrun simctl spawn booted log show --start "2025-11-15 10:00:00" --end "2025-11-15 11:00:00" | grep "DNP-"

Physical Device Logs:

# List connected devices
xcrun devicectl list devices

# Stream logs from physical device (requires device UDID)
xcrun devicectl device process launch --device <UDID> com.timesafari.dailynotification.test

# Or use Console.app for physical devices (easier)

---

Method 4: Validate Log Sequence (Automated)

When to use: Testing prefetch cycles, verifying complete execution

Using Validation Script:

# From log file
./scripts/validate-ios-logs.sh device.log

# From live stream
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.timesafari.dailynotification"' | ./scripts/validate-ios-logs.sh

# From filtered grep
grep -E "\[DNP-(FETCH|SCHEDULER|PLUGIN)\]" device.log | ./scripts/validate-ios-logs.sh

See: scripts/validate-ios-logs.sh for complete validation script

---

Common Log Prefixes

Plugin Logs (look for these):

Prefix	Meaning	Example
[DNP-PLUGIN]	Main plugin operations	[DNP-PLUGIN] configure() called
[DNP-FETCH]	Background fetch operations	[DNP-FETCH] BGTask handler invoked
[DNP-SCHEDULER]	Notification scheduling	[DNP-SCHEDULER] Scheduling notification
[DNP-STORAGE]	Storage/DB operations	[DNP-STORAGE] Persisted schedule
[DNP-DEBUG]	Debug diagnostics	[DNP-DEBUG] Plugin class found

Error Indicators:

• Error: - System errors
• Failed: - Operation failures
• ❌ - Visual error markers in logs
• ⚠️ - Warning markers

---

Troubleshooting Common Issues

Issue: No logs appearing

Solutions:

1. Check app is running: App must be launched to generate logs
2. Check filter: Remove filters to see all logs
3. Check log level: Some logs may be at debug level only
4. Restart logging: Close and reopen Console.app or restart log stream

Issue: Too many logs (noise)

Solutions:

1. Use specific filters: DNP- instead of DailyNotification
2. Filter by subsystem: subsystem:com.timesafari.dailynotification
3. Use time range: Only show logs from last 5 minutes
4. Use validation script: Automatically filters for important events

Issue: Can't see background task logs

Solutions:

1. Use Console.app: Background tasks show better in system console
2. Check Background App Refresh: Must be enabled for BGTask logs
3. Use log stream: xcrun simctl spawn booted log stream shows all logs
4. Check predicate: Use --predicate to filter specific subsystems

Issue: Physical device logs not showing

Solutions:

1. Use Console.app: Easiest for physical devices
2. Check device connection: Device must be connected and trusted
3. Check provisioning: Device must be provisioned for development
4. Use Xcode: Xcode → Window → Devices and Simulators → View Device Logs

---

Quick Reference Commands

Copy-Paste Ready Commands:

# Stream plugin logs (simulator)
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.timesafari.dailynotification"'

# Save logs to file
xcrun simctl spawn booted log stream > device.log 2>&1

# View recent errors
xcrun simctl spawn booted log show --last 5m | grep -i "error\|failed\|DNP-"

# Validate log sequence
grep -E "\[DNP-(FETCH|SCHEDULER|PLUGIN)\]" device.log | ./scripts/validate-ios-logs.sh

# Check app logs only
xcrun simctl spawn booted log stream --predicate 'process == "App"'

---

Log Levels and Filtering

iOS Log Levels:

• Default: Shows Info, Error, Fault
• Debug: Shows Debug, Info, Error, Fault
• Error: Shows Error, Fault only

To see debug logs:

• In Xcode: Product → Scheme → Edit Scheme → Run → Arguments → Environment Variables
• Add: OS_ACTIVITY_MODE=disable (shows all logs including debug)

Or use Console.app:

• Action menu → Include Info Messages
• Action menu → Include Debug Messages

---

References

• Testing Guide: doc/test-app-ios/IOS_PREFETCH_TESTING.md - Comprehensive testing procedures
• Test App Requirements: doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md - Debugging section
• Validation Script: scripts/validate-ios-logs.sh - Automated log sequence validation
• Main Directive: doc/directives/0003-iOS-Android-Parity-Directive.md - Implementation details

---

Status: 🎯 READY FOR USE
Maintainer: Matthew Raymer