Logpeek

logpeek -- Device Logs for Mobile Apps

When to Use

• App crashed or threw an exception
• Feature is not working as expected
• Need to see what the app logged during a specific action
• Debugging network errors, state issues, or silent failures
• User reports "it doesn't work" without details

Setup

npm install -g logpeek

Prerequisites (run logpeek doctor to verify):

• Android: adb available, emulator booted
• iOS: xcrun simctl available, simulator booted (macOS only)

Simulators/emulators only. No physical device support yet.

Commands

Log Collection Flags

Examples

# Get all logs from the last 5 minutes
logpeek --app com.example.myapp

# Get only error-level logs
logpeek --app com.example.myapp --level error

# Search for specific text in logs
logpeek --app com.example.myapp --grep "network"

# Combine: errors mentioning "timeout" in last 2 minutes
logpeek --app com.example.myapp --level error --grep "timeout" --last 2m

# Get React Native JS console logs only (-f implies --source framework)
logpeek --app com.example.myapp -f react-native

# Get Flutter framework logs only
logpeek --app com.example.myapp -f flutter

# Get logs from specific iOS simulator
logpeek --app com.example.myapp -d "iPhone 16"

# Get last 30 seconds after reproducing a bug
logpeek --app com.example.myapp --last 30s

# Widen the window for intermittent issues
logpeek --app com.example.myapp --last 30m -n 500

How It Works

Log Formatting

Logs are automatically formatted for readability. Raw platform logs are cleaned up to a consistent format:

15:47:37 INF [Network] GET /api/cart → 200 OK (142ms)
15:47:37 WRN [Auth] Session token expired, refreshing...
15:47:39 ERR [Inventory] Connection timeout after 5000ms

Format: <time> <level> [<category>] <message>

Android

• Queries adb logcat ring buffer with -d (dump and exit)
• Filters by app PID via adb shell pidof <package>
• Time window via logcat's -T flag
• If app crashed (no PID), automatically widens filter to include AndroidRuntime and FATAL EXCEPTION tags

iOS Simulator

• Queries unified logging via xcrun simctl spawn <udid> log show
• Resolves actual process name from CFBundleExecutable (not bundle ID)
• Filters by predicate: process == "<name>" OR subsystem == "<bundleId>"
• If no logs found, widens to include ReportCrash and SpringBoard for crash data
• Strips log show header lines automatically

React Native JS Logs

• On Android, console.log output appears in logcat under the ReactNativeJS tag
• On iOS, console.log appears under com.facebook.react.runtime.JavaScript in the new React Native runtime, or ReactNativeJS in older versions
• Use -f react-native to isolate framework logs

Flutter Logs

• On Android, Flutter logs appear under the flutter tag
• On iOS, Flutter logs appear under the app process in unified logging
• Use -f flutter to isolate framework logs

Source Filtering

When --framework is provided, --source framework is set automatically. You don't need to pass both.

Debugging Workflow

Step 1: Reproduce the issue

Have the user or agent trigger the bug on the device.

Step 2: Grab logs

logpeek --app <bundle-id> --last 1m

Use --last 1m right after reproducing to minimize noise.

Step 3: Narrow down

If too many results, filter:

• --level error for crashes and exceptions
• --grep "keyword" for specific errors
• -f react-native for framework-level issues
• -s native for platform-level issues

Step 4: Act on findings

Use log output to identify the root cause. Common patterns:

• FATAL EXCEPTION / java.lang.NullPointerException -- Android crash
• ReportCrash -- iOS crash
• ReactNativeJS errors -- JS-side exceptions
• Network timeouts, auth failures -- API issues

Platform Support

iOS simulator support requires macOS and Xcode Command Line Tools.

Error Handling

• No booted device -> "Start an emulator or simulator first"
• adb not found -> "Install Android SDK Platform-Tools"
• xcrun not found (macOS) -> "Install Xcode Command Line Tools: xcode-select --install"
• No tools found (Windows/Linux) -> "Install adb"
• App not running -> automatically shows crash-related logs
• No logs found -> "No logs found for in the last "
• Empty log buffer -> suggest widening --last window

Source: nomanr/logpeek — distributed by TomeVault.