3.6 KiB
3.6 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec |
|---|---|---|---|---|---|---|
| 01-backend-log-sinks | Backend log sinks | completed | 1 | plan.md | ../../specs/platform/requirements/diagnostic-logging.md |
Task 01: Backend log sinks
Acceptance
- Backend owns an owner-only
<ResolvedHomeDir>/logs/backend-logs.log, appends across same-UTC-day restarts, and rolls it at UTC midnight or the first startup after a day boundary. - Completed files use
backend-logs-YYYY-MM-DD.log; cleanup preserves only the current UTC day and two preceding days while leaving unrelated neighbors. - Normal, debug, and verbose file/stdout thresholds match the spec. The backend constructor does not add a new dependency on the legacy in-memory buffer.
- Log producers never wait for file or stdout I/O. Independent file/stdout queues enforce the exact entry/byte/reserved capacities and 256 KiB entry cap from the spec, shed debug/info first, and expose per-sink loss counters.
- A read-only atomic sink-statistics snapshot is available to the later bundle manifest without retaining log entries.
- Close drains for at most two seconds; terminal DPanic/Panic/Fatal behavior uses the bounded direct-stderr fallback from the spec.
- File-open and cleanup failures do not prevent startup. The backend reports fallback and retries file activation every 30 seconds.
- Destination and lumberjack rotation settings no longer influence backend logging; the daily writer exposes the strict active/dated file set consumed by the later bundle service.
Verification
cd apps/backend
go test ./internal/common/logger ./internal/common/config ./internal/backendapp
Files likely touched
apps/backend/internal/common/logger/logger.goapps/backend/internal/common/logger/async_sink.goapps/backend/internal/common/logger/daily_writer.goapps/backend/internal/common/logger/logger_test.goapps/backend/internal/common/logger/daily_writer_test.goapps/backend/internal/common/config/config.goapps/backend/internal/common/config/config_test.goapps/backend/internal/backendapp/main.go
Dependencies
None.
Parallelism
Sequential. This establishes the shared logging contract consumed by every later task.
Inputs
- Spec: What, Persistence guarantees, and the first five Scenarios.
- Plan: Backend / Fixed diagnostic file and dual sinks.
- ADR: fixed path, three-day UTC history, removed destination/rotation config.
- Existing patterns:
logger.NewLoggerand file-sink lifecycle.
Risks
- Cleanup must never use a broad glob or delete unrelated log-directory files.
- The daily writer needs an explicit persisted day marker or equally robust mechanism; an externally changed file mtime cannot silently choose its date.
- A rollover transaction journal must resume every tested crash point exactly once and must never overwrite an existing dated destination.
- Midnight rollover must serialize with writes and retry without losing the entry that observed the day boundary.
- Slow stdout/files must not cause request, agent, or workflow goroutines to wait on logging. The implementation must make its finite queue and recovery accounting testable with a blocked writer.
- A blocked stdout queue must not delay or shed entries accepted by a writable file queue, and vice versa.
Logger.WithFieldsandClosemust retain every backend sink.- File creation and cleanup must behave consistently on Windows and Unix.
Output contract
Report the threshold matrix, UTC rollover/retention behavior, cleanup matching
rule, files changed, exact test command/result, blockers or risks, and update
this task plus plan.md status in the same conversation.