37 lines
2.6 KiB
Markdown
37 lines
2.6 KiB
Markdown
# Run Log Ingest Contract
|
|
|
|
Logs are durable historical data. They are not transported as best-effort UI messages.
|
|
|
|
## Implemented Routes
|
|
|
|
- `POST /api/v1/run/logs/batches`: uploads one bounded log batch and receives an acknowledgement range.
|
|
- `POST /api/v1/log-streams/query`: queries stored log entries after a stream sequence cursor.
|
|
- `GET /api/v1/server-instances/{id}/logs/events`: browser-facing Server-Sent Events stream for replaying recent stored entries and pushing newly ingested platform log entries.
|
|
|
|
## Payloads
|
|
|
|
- `LogBatchIngestRequest`: run ID, session token, server instance ID, stream ID, source, sequence range, compression metadata, checksum, and bounded entries.
|
|
- `LogEntry`: sequence, timestamp, level, line, parser metadata, and redaction state.
|
|
- `LogBatchIngestResponse`: accepted sequence range, latest acknowledged sequence, duplicate flag, retry hint, and server time.
|
|
- `LogStreamCursorRequest`: stream ID, sequence cursor, and limit.
|
|
- `LogStreamCursorResponse`: ordered entries, next cursor, and latest acknowledged sequence.
|
|
- `LogStreamEventResponse`: safe browser event containing server ID, stream metadata, latest sequence, and one log entry.
|
|
|
|
Run-assigned Platform jobs use `job.<jobId>.<streamKey>` log stream IDs. Autonomous lifecycle bootstrap is not a Platform job, so it uses `run.<runEndpointId>.<serverInstanceId>.<streamKey>` and Platform creates the server-bound stream from the signed Run batch instead of looking for a job record.
|
|
|
|
## Local Spool
|
|
|
|
Run must write unacknowledged logs to a local spool/WAL before upload. Segments may be removed only after platform acknowledgement.
|
|
|
|
## Priority
|
|
|
|
Log flush has higher priority than artifact transfer. Artifact work must slow down when log spool pressure rises.
|
|
|
|
Log spool retry state is independent from artifact/file retry state. Acknowledged log batches may be removed even when artifact chunks are still pending, and artifact chunk acknowledgement must not alter log sequence state. Log ingest payloads carry bounded entries only and must not include artifact chunks, file bodies, host paths, raw credentials, or direct socket details.
|
|
|
|
The Run uploader flushes committed spool segments independently with bounded request contexts. A failed or partial acknowledgement leaves the segment pending for restart/retry; control heartbeat and job lifecycle polling do not wait for log or artifact flushes.
|
|
|
|
## Browser Channel
|
|
|
|
Browser live tail is a platform-owned SSE fan-out from durable ingest and cursor state. External log storage backends and optional game client bridge traffic remain separate channels. Artifact transfer uses its own lower-priority channel and must not be multiplexed through log ingest.
|