38 lines
2.6 KiB
Markdown
38 lines
2.6 KiB
Markdown
## Context
|
|
|
|
The Run process captures supervised stdout and stderr correctly, but `SpoolLogSink` persists one request per line. The durable uploader scans and uploads those files once per second within a five-second deadline. A startup burst therefore creates a durable backlog that reaches the platform long after the process emitted it.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Persist and upload contiguous same-stream entries in bounded multi-entry batches.
|
|
- Drain pending log work promptly while retaining retryable, acknowledgement-driven durability.
|
|
- Keep log upload independent from control, job, and artifact work.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Change platform log ingest routes or their contiguous-range contract.
|
|
- Add game-specific log behavior, browser polling, or unbounded in-memory buffering.
|
|
|
|
## Decisions
|
|
|
|
- Aggregate at the Run spool boundary. A short bounded in-memory builder groups entries only when their stream identity and sequence are contiguous, then writes one durable spool segment. This reduces both filesystem and HTTP work while preserving the existing spool retry model. Aggregating only in the uploader would retain thousands of per-line files and would not address disk pressure.
|
|
- Bound each durable batch by entry count and serialized payload size. A full batch is committed before later entries are accepted, so a crash can lose at most uncommitted in-memory lines; process capture will surface errors rather than silently discarding a committed range. A timer flush bounds latency for low-volume output.
|
|
- Flush pending batches repeatedly until no work remains or the channel work budget expires. The uploader remains in its own loop and uses a bounded context, so control and job loops remain independent.
|
|
- Keep platform acknowledgements range-based. Batches remain immutable after persistence and are removed only when the existing accepted range covers them.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Crash before a partial batch is committed] → Keep the aggregation window small and flush on process completion and uploader shutdown.
|
|
- [Large entry or encoded payload] → Commit that entry alone only when it satisfies the existing protocol bounds; reject unsafe oversized entries through the current validation path.
|
|
- [Backlog monopolizes a tick] → Use a finite per-cycle deadline and yield to the next scheduler turn.
|
|
|
|
## Migration Plan
|
|
|
|
Existing one-entry spool files remain valid and flush through the unchanged acknowledgement logic. New Run binaries begin producing multi-entry segments; rollback remains safe because the old spool reader already accepts a batch with multiple entries.
|
|
|
|
## Open Questions
|
|
|
|
- None.
|