Gateway log streams
admin.logs.stream(projectId) returns an open NDJSON byte stream from the gateway. The key needs logs:read and access to that project’s mode. The stream includes request metadata, while retained completion content is restricted to authenticated synthetic Sandbox requests. See content retention before expecting prompt/output text or treating a tail as an archive.
const controller = new AbortController();
const stream = await admin.logs.stream(projectId, {
signal: controller.signal,
// after: savedCursor,
});
const reader = stream.getReader();
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(value);
}
} finally {
await reader.cancel();
reader.releaseLock();
}Byte chunks are not record boundaries. If parsing records, buffer until a newline before calling JSON.parse. Preserve incomplete text across reads. Save an entry’s cursor only after processing it, then pass it as after when opening a replacement stream. A cursor is useful only while the gateway retains that stream history. The tail is count-trimmed, not a permanent archive or a fixed-duration retention guarantee; stored Usage records are separate.
Use the abort controller to stop a stream when its consumer exits. The SDK returns the stream but does not supervise reconnection for you. gatewayBaseUrl must address the correct deployment, independently of the app API URL.
CLI supervision
modem-cli logs
modem-cli logs --project-id PROJECT_IDThe CLI reads accessible projects once at startup, opens one stream per project, removes heartbeat records and emits project-tagged NDJSON. It keeps the last emitted cursor in memory and reconnects transient failures with exponential backoff, honoring Retry-After when supplied. It has no persistent --after option; restarting the command starts a new tail.
A terminal failure for one project does not stop healthy projects. If the selected project fails terminally, or every selected project becomes unavailable, the command exits with an error. Ctrl-C/SIGTERM stops streams. Data is written to stdout; connection status and warnings go to stderr.
These live gateway logs and the app’s retained usage/request history serve different purposes. Do not infer complete HTTP attempt counts or permanent retention from a log tail.