simctl-stream-logs

Stream real-time console logs from iOS simulator with filtering, severity classification, deduplication, and statistics summary.

What it does

Streams console logs from a simulator in real-time, with support for filtering by process or custom predicates. Captures logs for a specified duration and returns:

• Structured log entries with timestamps, process names, and per-line severity

• Statistics summary (totalLines, errors, warnings, info, debug)

• Top errors and warnings (deduplicated, capped at 15 each)

• Sample tail of raw log output

Parameters

• udid (string, required): Simulator UDID (from simctl-list)

• bundleId (string, optional): Filter logs to specific app bundle ID

• predicate (string, optional): Custom NSPredicate for log filtering

• duration (number, optional): Capture duration in seconds (default: 10)

• capture (boolean, optional): Whether to capture logs (default: true)

• severity (string | string[], optional): Comma-separated or array of severity levels to include in the returned items. Allowed values: error, warning, info, debug. Default: all four. Statistics always count all severities regardless of this filter.

Severity Classification

Each log line is classified by case-insensitive pattern matching:

Deduplication

Error and warning lines are deduplicated before appearing in topErrors / topWarnings. The deduplication signature is computed by stripping timestamps (YYYY-MM-DD HH:MM:SS) and process IDs ([1234]) then collapsing whitespace. Duplicate occurrences are collapsed into a single entry with a count field.

Returns

JSON response with:

• logs: Filtered log entries (severity-filtered, first 100 items)

  • count, predicate, bundleId, duration, severityFilter, items[]

• statistics: { totalLines, errors, warnings, info, debug }

• topErrors: Deduplicated error lines, up to 15, each with message and count

• topWarnings: Deduplicated warning lines, up to 15, each with message and count

• sampleTail: Last 20 raw log lines

• guidance: Human-readable summary strings

Examples

Stream all logs for 10 seconds

await streamLogsTool({ udid: 'device-123' })

Stream errors and warnings only for specific app

await streamLogsTool({
  udid: 'device-123',
  bundleId: 'com.example.MyApp',
  duration: 30,
  severity: 'error,warning',
})

Stream with custom predicate

await streamLogsTool({
  udid: 'device-123',
  predicate: 'eventMessage CONTAINS "Error" OR eventMessage CONTAINS "Warning"',
  duration: 20,
})

Predicate Syntax

Supports NSPredicate syntax for filtering:

• Process filtering: process == "MyApp"

• Content filtering: eventMessage CONTAINS "keyword"

• Severity filtering: messageType == "Error"

• Combined filters: process == "MyApp" AND eventMessage CONTAINS "network"

Common predicates:

• process == "com.example.MyApp" - Filter by bundle ID

• eventMessage CONTAINS "Error" - Show only errors

• subsystem == "com.example.networking" - Filter by subsystem

• messageType IN {"Error", "Fault"} - Show errors and faults

Common Use Cases

1. App debugging: Stream logs for specific app during testing

2. Error monitoring: Filter for errors and warnings via severity param

3. Network debugging: Monitor network-related log messages

4. Performance tracking: Capture logs during performance tests

5. Integration testing: Verify expected log output during test runs

Important Notes

• Timeout buffer: Command timeout is duration + 5 seconds for safety

• Buffer size: 10MB buffer for log capture to prevent overflow

• First 100 logs: Returns first 100 severity-filtered log entries to avoid token overflow

• Statistics always complete: Counts cover all lines regardless of severity filter

• Dedup on errors/warnings: topErrors and topWarnings collapse repeated messages

Error Handling

• Missing udid: Error if udid is not provided

• Simulator not found: Validates simulator exists

• Command timeout: Times out if duration exceeds limit

• Buffer overflow: May lose logs if output exceeds 10MB buffer

Duration Guidelines

• Quick check: 5-10 seconds for basic log verification

• Feature testing: 15-30 seconds for testing specific features

• Integration tests: 30-60 seconds for full test scenarios

• Debug sessions: 60+ seconds for deep debugging sessions