ios-android-logs · diff
git:20260125.c366932 to git:20261011.86834d4
81 added, 337 removed. Audit A to A.
---
name: ios-android-logs
- description: Guide to accessing device logs on iOS and Android for Capacitor apps. Covers command-line tools, GUI applications, filtering, and real-time streaming. Use this skill when users need to view device logs for debugging.
+ description: Gets, filters, streams, and saves logs and crash reports from Capacitor apps on iOS Simulator, iPhone, Android emulator and devices. Explains where Capacitor output goes (iOS bridge and mirrored JS console lines are stdout-only, so missing from Console.app and `log stream`; Android tags `Capacitor` and `Capacitor/Console`). Covers `xcrun simctl spawn booted log stream --predicate`, `simctl launch --console-pty`, `xcrun devicectl device process launch --console`, `log collect --device-udid`, Console.app, devicectl `systemCrashLogs`, `adb logcat --pid`, `-b crash`, Android Studio `package:mine`, tombstones, ANRs, `adb bugreport`. Use for "how do I see logs", "console.log not showing on device", "no logs in Console.app", "get the crash log", "logcat too noisy". Do not use for diagnosing the bug once logs are in hand (debugging-capacitor), production crash SDKs (capacitor-native-observability), MCP log tooling (capacitor-mcp), or profiling (capacitor-performance).
---
- # iOS and Android Device Logs
-
- Complete guide to viewing and filtering device logs on iOS and Android.
-
- ## When to Use This Skill
-
- - User needs to see device logs
- - User is debugging crashes
- - User wants to filter logs by app
- - User needs real-time log streaming
- - User asks "how to see logs"
-
- ## Quick Commands
-
- ```bash
- # iOS - Stream logs from connected device
- xcrun devicectl device log stream --device <UUID>
-
- # iOS - Stream from simulator
- xcrun simctl spawn booted log stream
-
- # Android - Stream all logs
- adb logcat
-
- # Android - Filter by package
- adb logcat --pid=$(adb shell pidof com.yourapp.id)
- ```
-
- ## iOS Logs
-
- ### Method 1: Console.app (GUI)
-
- 1. Open **Console.app** (Applications > Utilities)
- 2. Select your device in sidebar
- 3. Click "Start Streaming"
- 4. Use search to filter:
- - By process: `process:YourApp`
- - By subsystem: `subsystem:com.yourapp`
- - By message: `"error"`
-
- ### Method 2: devicectl (CLI - Recommended)
-
- ```bash
- # List connected devices
- xcrun devicectl list devices
-
- # Stream logs from specific device
- xcrun devicectl device log stream --device <DEVICE_UUID>
-
- # Stream with predicate filter
- xcrun devicectl device log stream --device <DEVICE_UUID> \
- --predicate 'process == "YourApp"'
-
- # Stream specific log levels
- xcrun devicectl device log stream --device <DEVICE_UUID> \
- --level error
-
- # Save to file
- xcrun devicectl device log stream --device <DEVICE_UUID> \
- --predicate 'process == "YourApp"' > app_logs.txt
- ```
-
- ### Method 3: simctl for Simulators
-
- ```bash
- # Stream logs from booted simulator
- xcrun simctl spawn booted log stream
-
- # Filter by process
- xcrun simctl spawn booted log stream --predicate 'process == "YourApp"'
-
- # Filter by subsystem
- xcrun simctl spawn booted log stream --predicate 'subsystem == "com.yourapp"'
-
- # Show only errors
- xcrun simctl spawn booted log stream --level error
-
- # Combine filters
- xcrun simctl spawn booted log stream \
- --predicate 'process == "YourApp" AND messageType == error'
- ```
-
- ### Method 4: Xcode Device Logs
-
- 1. Window > Devices and Simulators
- 2. Select device
- 3. Click "Open Console"
- 4. Or: View device logs for crash reports
-
- ### iOS Log Predicate Examples
-
- ```bash
- # Process name
- --predicate 'process == "YourApp"'
-
- # Contains text
- --predicate 'eventMessage contains "error"'
-
- # Subsystem
- --predicate 'subsystem == "com.yourapp.plugin"'
-
- # Category
- --predicate 'category == "network"'
-
- # Log level
- --predicate 'messageType == error'
-
- # Combined
- --predicate 'process == "YourApp" AND messageType >= error'
-
- # Time-based (last 5 minutes)
- --predicate 'timestamp > now - 5m'
- ```
-
- ### iOS Log Levels
-
- | Level | Description |
- |-------|-------------|
- | `default` | Default messages |
- | `info` | Informational |
- | `debug` | Debug (hidden by default) |
- | `error` | Error conditions |
- | `fault` | Fault/critical |
-
- ## Android Logs
-
- ### Method 1: adb logcat (CLI)
-
- ```bash
- # Basic log stream
- adb logcat
-
- # Clear logs first, then stream
- adb logcat -c && adb logcat
-
- # Filter by tag
- adb logcat -s MyTag:D
-
- # Filter by priority
- adb logcat *:E # Only errors and above
-
- # Filter by package name
- adb logcat --pid=$(adb shell pidof com.yourapp.id)
-
- # Filter by multiple tags
- adb logcat -s "MyPlugin:D" "Capacitor:I"
-
- # Save to file
- adb logcat > logs.txt
-
- # Save to file with timestamp
- adb logcat -v time > logs.txt
- ```
-
- ### Method 2: Android Studio Logcat (GUI)
-
- 1. View > Tool Windows > Logcat
- 2. Use filter dropdown:
- - Package: `package:com.yourapp`
- - Tag: `tag:MyPlugin`
- - Level: `level:error`
- 3. Create saved filters for quick access
-
- ### Method 3: pidcat (Better CLI Tool)
-
- ```bash
- # Install pidcat
- pip install pidcat
-
- # Stream logs for package
- pidcat com.yourapp.id
-
- # With tag filter
- pidcat -t MyPlugin com.yourapp.id
- ```
-
- ### Android Log Priority Levels
-
- | Letter | Priority |
- |--------|----------|
- | V | Verbose |
- | D | Debug |
- | I | Info |
- | W | Warn |
- | E | Error |
- | F | Fatal |
- | S | Silent |
-
- ### adb logcat Format Options
-
- ```bash
- # Different output formats
- adb logcat -v brief # Default
- adb logcat -v process # PID only
- adb logcat -v tag # Tag only
- adb logcat -v time # With timestamp
- adb logcat -v threadtime # With thread and time
- adb logcat -v long # All metadata
-
- # Colorized output
- adb logcat -v color
-
- # Show recent logs (last N lines)
- adb logcat -d -t 100
-
- # Show logs since timestamp
- adb logcat -v time -T "01-25 10:00:00.000"
- ```
-
- ### Common Android Filters
-
- ```bash
- # Capacitor core logs
- adb logcat -s "Capacitor:*"
-
- # Plugin-specific logs
- adb logcat -s "CapacitorNativeBiometric:*"
-
- # WebView logs (JavaScript console)
- adb logcat -s "chromium:*"
-
- # JavaScript errors
- adb logcat | grep -i "js error\|uncaught"
-
- # Crash logs
- adb logcat | grep -iE "fatal|crash|exception"
-
- # Network logs
- adb logcat -s "OkHttp:*" "NetworkSecurityConfig:*"
- ```
-
- ## Viewing Crash Logs
-
- ### iOS Crash Logs
-
- ```bash
- # Copy crash logs from device
- xcrun devicectl device copy crashlog --device <UUID> ./crashes/
-
- # View in Console.app
- # User Diagnostics Reports section
-
- # Or find at:
- # Device: Settings > Privacy > Analytics & Improvements > Analytics Data
- # Mac: ~/Library/Logs/DiagnosticReports/
- ```
-
- ### Android Crash Logs
-
- ```bash
- # Get tombstone (native crash)
- adb shell cat /data/tombstones/tombstone_00
+ # iOS and Android Logs for Capacitor Apps
- # Get ANR traces
- adb pull /data/anr/traces.txt
+ Pick the log channel that actually carries the message you need, filter to the app, capture to a file, hand off to diagnosis.
- # Get bugreport (comprehensive)
- adb bugreport > bugreport.zip
- ```
+ ## When to Use
- ## MCP Integration
+ TRIGGER when:
+ - User asks how to view, stream, filter, or save device/simulator logs.
+ - `console.log` output or `⚡️` Capacitor lines are missing on iOS/Android.
+ - User needs a crash report (`.ips`, tombstone, ANR) from a device or simulator.
+ - Logcat or the unified log is too noisy; user wants only their app or plugin.
+ - A log command fails or misbehaves: `--level error` still shows everything, `unable to find utility "devicectl"`, `Error: Unexpected argument 'log'`, `adb: no devices/emulators found`.
- Use MCP tools to fetch logs programmatically:
+ Do not use:
+ - Interpreting the error and fixing the app -> `debugging-capacitor`.
+ - Production crash/ANR reporting (Sentry, Crashlytics, Datadog) -> `capacitor-native-observability`.
+ - AI agent log streaming via MCP servers -> `capacitor-mcp`.
+ - CPU/memory profiling -> `capacitor-performance`.
+ - UIScene lifecycle migration -> `capacitor-uiscene-migration`.
- ```typescript
- // Example MCP tool for fetching iOS logs
- const logs = await mcp.ios.streamLogs({
- device: 'booted',
- predicate: 'process == "YourApp"',
- level: 'debug',
- });
+ ## Where Capacitor Output Goes (the main trap)
- // Example MCP tool for Android logs
- const androidLogs = await mcp.android.logcat({
- package: 'com.yourapp.id',
- level: 'D',
- });
- ```
+ | Source | iOS | Android |
+ |---|---|---|
+ | Capacitor bridge messages (`⚡️ Loading app at ...`, `⚡️ To Native ->`, errors) | **stdout only** (`print`) | logcat tag `Capacitor` and `Capacitor/<Sub>` |
+ | JS `console.log/warn/error` mirrored natively | stdout as `⚡️ [log] - ...` | logcat tag `Capacitor/Console` as `File: ... - Line N - Msg: ...` |
+ | JS console, full fidelity (objects, stack traces) | Safari Web Inspector | `chrome://inspect` |
+ | Plugin/app code using `os.Logger` / `NSLog` | unified log (Console.app, `log stream`) | n/a |
+ | Plugin code using `android.util.Log` / Capacitor `Logger` | n/a | logcat |
+ | Native crash | `.ips` crash report | `FATAL EXCEPTION` in logcat + crash buffer; tombstone for native code |
- ## Log Parsing Tips
+ Consequences:
+ - On iOS, Console.app and `log stream` will **not** show Capacitor's `⚡️` lines or mirrored JS console. Use Xcode's console, `xcrun simctl launch --console-pty`, or `xcrun devicectl device process launch --console`.
+ - Mirroring obeys `loggingBehavior` (`none` | `debug` | `production`, default `debug`): Release builds produce no Capacitor logs unless set to `production`.
+ - The iOS process name is the executable (`App` in the Capacitor template), not the display name. Filter with `process == "App"`.
- ### Extract JavaScript Errors
+ ## Quick Commands
```bash
- # iOS - JavaScript console logs
- xcrun simctl spawn booted log stream \
- --predicate 'eventMessage contains "JS:"'
-
- # Android - WebView console
- adb logcat chromium:I *:S | grep "console"
- ```
+ # iOS Simulator: Capacitor + JS console (stdout), relaunching the app
+ xcrun simctl launch --console-pty --terminate-running-process booted com.example.app
- ### Filter Network Requests
+ # iOS Simulator: unified log for the app (os_log / NSLog / system messages)
+ xcrun simctl spawn booted log stream --level debug --predicate 'process == "App"'
- ```bash
- # iOS
- xcrun simctl spawn booted log stream \
- --predicate 'subsystem == "com.apple.network"'
+ # iPhone: install + launch with stdout attached (Xcode 15+ devicectl)
+ xcrun devicectl list devices
+ xcrun devicectl device process launch --console --terminate-existing --device <id> com.example.app
- # Android
- adb logcat -s "NetworkSecurityConfig:*" "OkHttp:*"
- ```
+ # iPhone: unified log snapshot of the last 10 minutes
+ sudo log collect --device-udid <udid> --last 10m --output /tmp/iphone.logarchive
+ log show /tmp/iphone.logarchive --predicate 'process == "App"' --info --debug
- ### Monitor Memory
+ # Android: only this app (re-run after each app restart, PID changes)
+ adb logcat --pid="$(adb shell pidof -s com.example.app)"
- ```bash
- # iOS - Memory pressure
- xcrun simctl spawn booted log stream \
- --predicate 'eventMessage contains "memory"'
+ # Android: Capacitor + JS console only
+ adb logcat -s Capacitor:V Capacitor/Console:V
- # Android - Memory info
- adb shell dumpsys meminfo com.yourapp.id
+ # Android: crashes only
+ adb logcat -b crash
```
- ## Troubleshooting
-
- ### Issue: No Logs Showing
-
- **iOS**:
- - Ensure device is trusted: Xcode > Window > Devices
- - Try restarting log stream
- - Check Console.app filters
-
- **Android**:
- - Enable USB debugging
- - Run `adb devices` to verify connection
- - Try `adb kill-server && adb start-server`
+ ## Procedure
- ### Issue: Too Many Logs
+ 1. **Identify target**: Simulator/emulator vs physical device; Debug vs Release; which layer emitted the message (table above).
+ 2. **Check connectivity**: `xcrun simctl list devices booted`, `xcrun devicectl list devices` (device must be unlocked, trusted, Developer Mode on), `adb devices -l`.
+ 3. **Clear and reproduce**: `adb logcat -c` on Android; on iOS start the stream before relaunching the app.
+ 4. **Filter early** by process/PID, then by subsystem/tag, then by text. Never paste unfiltered system logs into a conversation.
+ 5. **Save** to a file (`> app.log`, `.logarchive`, `adb bugreport`) when the user needs to share it; redact tokens, emails, and auth headers before sharing outside the team.
+ 6. **Hand off** the relevant lines to `debugging-capacitor` for root-cause work.
- Use filters:
- ```bash
- # iOS - Only your app
- --predicate 'process == "YourApp" AND messageType >= info'
+ ## Error Handling
- # Android - Only your package
- adb logcat --pid=$(adb shell pidof com.yourapp.id)
- ```
+ | Message | Fix |
+ |---|---|
+ | `--level error` still shows every message | `log stream --level` only understands `default`, `info`, `debug` (it sets the floor, not a ceiling). Filter errors with `--predicate 'messageType == error OR messageType == fault'`. |
+ | `xcrun: error: unable to find utility "devicectl"` | Active dev dir is Command Line Tools. `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`. |
+ | `Error: Unexpected argument 'log'` (devicectl) | `devicectl` has no log streaming subcommand. Use `--console` for stdout, Console.app or `log collect --device-udid` for unified logs. |
+ | `log collect` fails with a permission error | Run with `sudo`; device must be unlocked and trusted. |
+ | `No devices are booted.` (simctl) | `xcrun simctl boot "<device name>"` or open Simulator. |
+ | `adb: no devices/emulators found` / `unauthorized` | Enable USB debugging, accept the RSA prompt, `adb kill-server && adb start-server`. |
+ | `adb logcat --pid=` prints everything / errors | App not running so `pidof` returned nothing. Launch the app first. |
+ | No `Capacitor/Console` lines on Android | `loggingBehavior: 'none'`, or Release build with default `debug`. |
+ | JS logs show but objects print as `[object Object]` | Native mirroring stringifies; use the WebView inspector for structured output. |
- ### Issue: Missing Debug Logs
+ ## Verification
- **iOS**: Debug logs are hidden by default
- ```bash
- # Enable debug logs
- xcrun simctl spawn booted log stream --level debug
- ```
+ - iOS sim: launch with `--console-pty`, see `⚡️ Loading app at capacitor://localhost` and a test `console.log('log-check')` as `⚡️ [log] - log-check`.
+ - iOS device: same via `devicectl device process launch --console`.
+ - Android: `adb logcat -s Capacitor/Console:V` shows `Msg: log-check`.
+ - Unified log: a plugin `Logger(subsystem: "com.example.app", category: "test").info("log-check")` appears with `--predicate 'subsystem == "com.example.app"' --level info`.
- **Android**: Ensure log level is set correctly
- ```kotlin
- Log.d("Tag", "Debug message") // D level
- ```
+ ## References
- ## Best Practices
+ Only load a reference when its topic is in play.
- 1. **Use structured logging** - Include context in log messages
- 2. **Add timestamps** - Helps correlate events
- 3. **Filter early** - Don't stream all logs
- 4. **Save important logs** - Redirect to file for later analysis
- 5. **Use log levels appropriately** - Debug for dev, error for production
+ | File | Load when |
+ |---|---|
+ | `references/ios-logs.md` | Unified log predicates, Console.app, `log collect`/`log show`, iOS crash reports via devicectl/Xcode, adding `os.Logger` to a plugin |
+ | `references/android-logs.md` | logcat buffers/formats/filters, Android Studio Logcat queries, ANRs, tombstones, bugreports, WebView (`chromium`) noise |
## Resources
- - iOS Unified Logging: https://developer.apple.com/documentation/os/logging
- - Android Logcat: https://developer.android.com/studio/debug/logcat
- - devicectl Reference: https://developer.apple.com/documentation/devicemanagement
+ - https://developer.apple.com/documentation/os/logging
+ - https://developer.apple.com/documentation/xcode/acquiring-crash-reports-and-diagnostic-logs
+ - https://developer.android.com/tools/logcat
+ - https://developer.android.com/studio/debug/logcat
+ - https://capacitorjs.com/docs/config