Logs And Crashes

This covers iOS sessions. Call sim_api /crashes first. If it returns 404 Not found, the session’s preview server predates these routes: fall back to agent-device logs (see controllers.md) and tell the user crash reports aren’t available on that session. Don’t call /logs there, because older servers stream it without end.

Reach the preview API

simulator:get --json returns remoteConfig.previewApiUrl, the preview server’s API URL with the session token already in its query. Keep it in a shell variable and don’t print it: the token grants control of the session. As with simulator:exec, run this from the Expo project directory. Pass --id with the session you are driving, because another agent can replace the dotenv session between your commands.

If your shell does not keep variables between commands, repeat these lines at the start of each command. Each repeat runs simulator:get again, which takes a few seconds, so put related reads in one command. Only call /crashes, /crashes/<id>, and /logs. Don’t call /api: its response includes the exec token. Calls to the preview server do not reset the session’s idle timer.

Catch a crash with its log tail

The device log only runs while something holds it, so start holding it before you reproduce the crash. A crash that happens while nothing holds the log still gets a report, but its tail is empty. Hold it with a /crashes stream opened with ?tail=1, which also writes each crash event to $EVENTS.log:

Reproduce only after log held. Otherwise the command prints the error: 401 means the session ended or its token changed, and 404 means the server predates these routes. --max-time 300 ends the hold after 5 minutes even if nothing kills it; start it again for a longer run. Without the stream, call sim_api /logs "snapshot=1&follow=1&limit=1" more often than every 8 seconds: the log stops 8 seconds after its last reader.

Right after a session boots, the simulator writes many log lines for a minute or two, and a crash in that window can come back without its tail (logTailSource of buffer-rolled-past or no-app-lines, no lines). If that happens, reproduce again once logging settles; the new occurrence gets its tail.

An empty crashes array right after a crash means “not yet”, not “nothing happened”. meta.reportDelaySeconds estimates the delay, and meta.status says whether collection is running (watching) at all.

Read a crash

The list gives one record per crash signature, with signal, exceptionType, culpritFrame, bundleId, pid, count, and occurrenceTimes (each retained occurrence’s key, oldest first). Repeats of the same crash collapse into one record with a higher count.

The detail returns {record, occurrence, report, reportError}:

• occurrence.frames is that occurrence’s stack. The first frame with appOwned: true is usually where to look in the user’s code.
• occurrence.logTail holds the app’s own device-log lines (NDJSON) from at or before the crash. occurrence.logTailSource says how it was chosen:
  • app-windowed: lines found.
  • buffer-rolled-past: the buffer no longer reached back that far, or nothing held the log when the crash happened.
  • no-app-lines: the window was there, but the app logged nothing.
  • none: nothing was buffered for the device, usually because nothing held the log. It is also none when the report has no timestamp or process name.
• occurrence.appVersion, buildVersion, and faultingQueue are per occurrence.
• report is the full .ips text. When it is null, reportError says why. The detail can be large, so print only the fields you need.

Read the device log

The JSON has lines ({seq, at, raw}, where raw is one NDJSON log entry with processImagePath, processID, eventMessage, and messageType), latestSeq, oldestSeq, and status (streaming, restarting, or stopped). streamError keeps the last stream error, so it can be set while status is streaming. Keep snapshot=1: without it, /logs is an event stream that does not end. Without follow=1, /logs only reads what is already buffered, and stopped means nothing is holding the log. The first follow=1 read after the log was idle can return no lines, so read again after a second or two.

To keep only the user’s app, match processImagePath ending in the app’s executable name (its CFBundleExecutable; app paths contain /Containers/Bundle/Application/), or processID for one launch.

A busy simulator can log hundreds of lines a second, and the buffer is capped at about 4 MB, so it may hold only seconds to minutes of history. Read right after the event you care about; if since is older than oldestSeq, those lines are gone.

What the user sees

The same data is in the browser preview the user opens from webPreviewUrl: the device log in the Logs drawer (toolbar icon), and crashes in the Crashes section of the Tools panel, where each crash opens its stack, log tail, and .ips. Point the user there when they want to look for themselves.