Files
clean-architecture-backend-…/docs/superpowers/specs/2026-09-18-bootstrap-structured-runtime-logging.md
T

54 lines
2.5 KiB
Markdown

# Bootstrap Structured Runtime Logging
## Goal
Finish BOOT-009 by removing the remaining unstructured operational log events from app-bootstrap without changing their severity or failure semantics.
## Existing structured paths
- StartupFailures owns startup failure ERROR logs with startup.phase, error.code, error.category and bounded root-cause fields.
- MigrationStartupRunner emits startup.phase on migration INFO logs.
- LoggingAbortPolicy emits error.code, error.category, executor_name, policy and queue_size.
- RuntimeWarnings owns metric-unavailable and setting-fallback WARN frames.
## Remaining paths
Three runtime paths still emit prose-only warning/error events:
1. fileserver cleanup batch failure;
2. outbox relay scheduler unexpected failure before the next polling tick;
3. distributed-lock lease expiry observed during close.
Fileserver cleanup success also emits counters as prose only, so those bounded counters become structured values while preserving the same plain-text numbers.
## Field rules
- capability: stable bounded capability name.
- operation: stable bounded operation name.
- warning.kind: bounded warning classifier for continuing/degraded behavior.
- retry.disposition: bounded description of the already-existing retry behavior.
- cleanup.*: bounded numeric batch outcome fields.
- Do not invent error.code when the caught exception is broader than one OperationalError.
- Do not promote raw lock keys into a structured field; the current human-readable message is kept, while structured fields remain bounded and non-cardinality-amplifying.
The field dictionary is `docs/observability/log-fields.md`.
## Compatibility
- log levels stay unchanged;
- exception propagation/swallowing stays unchanged;
- retry schedules stay unchanged;
- existing human-readable messages remain recognizable;
- no business behavior changes.
## Verified result
- Fileserver cleanup success/failure events carry bounded structured fields;
- outbox relay unexpected failures carry capability, operation and next-tick retry disposition without an invented error code;
- distributed-lock lease-expiry warnings carry bounded classification while the raw lock key is not promoted to a structured dimension;
- behavior tests inspect actual Logback structured arguments: PASS;
- direct app-bootstrap WARN/ERROR inventory reports every event as structured or emitted by the structured warning/failure helpers;
- app-bootstrap full test and architectureTest: PASS;
- app-bootstrap Spotless: PASS;
- git diff --check: PASS.