Skip to content

Commit eec35e9

Browse files
authored
fix(journal): clarify failure diagnostics (#4472)
1 parent 2470323 commit eec35e9

4 files changed

Lines changed: 11 additions & 6 deletions

File tree

‎packages/session-journal/src/__tests__/session-event-log-window.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,8 @@ test('an unreadable window sidecar refuses required rotation and preserves the t
351351
const failure = diagnostics.find((record) => record.phase === 'session_event_log_write_failed');
352352
assert.equal(failure?.data.reason, 'maintenance-failed');
353353
assert.equal(failure?.data.operation, 'rotation');
354+
assert.equal(failure?.data.errno, undefined);
355+
assert.equal(failure?.data.error?.code, 'COMMAND_FAILED');
354356
assert.equal(failure?.data.error?.details?.reason, EVENT_LOG_WINDOW_UNVERIFIED_REASON);
355357
assert.equal(readError(eventLogPath, '0').details?.reason, EVENT_LOG_WINDOW_UNVERIFIED_REASON);
356358
});

‎packages/session-journal/src/session-event-log.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@ function reportEventLogFailure(
111111
path: eventLogPath,
112112
reason,
113113
operation,
114-
errno: (error as NodeJS.ErrnoException | undefined)?.code,
114+
errno:
115+
error instanceof AppError ? undefined : (error as NodeJS.ErrnoException | undefined)?.code,
115116
error: error === undefined ? undefined : normalizeError(error),
116117
},
117118
});

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1115,7 +1115,7 @@ agent-device network dump 25 --include headers --platform web # Browser requests
11151115
- `logs start` appends to `app.log` and rotates at 5 MB. Override with `AGENT_DEVICE_APP_LOG_MAX_BYTES` and `AGENT_DEVICE_APP_LOG_MAX_FILES`; set `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` to a comma-separated regex list for write-time redaction. Commas inside a `{m,n}` quantifier, `[...]`, or `(...)` stay in their pattern; write `\,` for any other literal comma. If a pattern does not compile, `logs start` fails with `INVALID_ARGS`, `details.reason: "app_log_redact_pattern_invalid"`, and the zero-based `details.patternIndex` of that comma-separated field (empty fields count); the pattern text is not echoed. On Apple simulators, `logs start` returns once the simulator log stream is running, so lines that the app logs after that are captured. If the stream does not start within 10 s, `logs start` fails with `details.reason: "simulator-log-stream-launch-timeout"`.
11161116
- `open` prints `Session state: <path>`; see [Sessions](/docs/sessions#find-a-sessions-logs-and-artifacts) for the files it contains.
11171117
- `events` reads the session timeline, which leaves out user-entered content; `--no-record` suppresses `action.recorded` entries. `events.ndjson` rotates before an entry would exceed 5 MiB (`AGENT_DEVICE_EVENT_LOG_MAX_BYTES`) and keeps one generation. Cursors stay valid across rotation; a cursor older than the retained window fails with `details.reason: "EVENT_LOG_CURSOR_EXPIRED"` and `details.earliestCursor`. If the retained files were edited or deleted, `events` fails with `details.reason: "EVENT_LOG_WINDOW_UNVERIFIED"`.
1118-
- Events are best effort: a line over the file cap or 16 MiB is dropped. An event that would exceed a session's pending limit of 128 events or 16 MiB is also dropped. The command can still succeed. Drops and write failures emit `session_event_log_write_failed`; see [Sessions](/docs/sessions#find-a-sessions-logs-and-artifacts). Failed entries are not replayed.
1118+
- Events are best effort: a line over the file cap or 16 MiB is dropped. An event that would exceed a session's pending or in-flight limit of 128 events or 16 MiB is also dropped. The command can still succeed. Use `--debug` to capture `session_event_log_write_failed` diagnostics for drops and write failures; see [Sessions](/docs/sessions#find-a-sessions-logs-and-artifacts). Failed entries are not replayed.
11191119
- `network dump [limit] [summary|headers|body|all]` parses recent HTTP(s) entries from `app.log`, or from managed `agent-browser` request history on web; `network log` is an alias. Prefer `--include` over the positional detail level. It scans up to 4000 log lines, returns up to 200 entries, and truncates fields at 2048 characters. Web does not expose bodies.
11201120
- On iOS, `network dump` can miss requests the app does not log and cannot name every request on a reused connection, so treat a missing endpoint as unproven. See [Network inspection](/docs/debugging-profiling#network-inspection) for per-platform behavior.
11211121

‎website/docs/docs/sessions.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,12 @@ placeholders. `--no-record` suppresses recorded action entries; request start/fi
4242
record command, status, and timing.
4343

4444
The timeline is best effort. An event line larger than the configured file cap or 16 MiB is dropped.
45-
Each session can have at most 128 events and 16 MiB of event data awaiting a write; further events are
46-
dropped until capacity is available. These drops do not fail the command. Look for the
47-
`session_event_log_write_failed` diagnostic to identify missing entries, including write or rotation
48-
failures. Failed entries are not replayed.
45+
The per-session limit is 128 events and 16 MiB of event data, including the write in progress.
46+
Further events are dropped until capacity is available. These drops do not fail the command, and
47+
failed entries are not replayed. To capture write or rotation failure diagnostics while reproducing
48+
missing entries, run the command with `--debug`, then look for `session_event_log_write_failed` in
49+
`requests/<request-id>.ndjson` inside the session artifact directory. An active `trace` also records
50+
these diagnostics in its trace file.
4951

5052
To debug a specific run, start with the session artifact directory. The top-level daemon log only
5153
covers daemon startup and lifecycle issues.

0 commit comments

Comments
 (0)