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

40 lines
1.9 KiB
Markdown

# Bootstrap Structured Log Fields
## Goal
Close BOOT-009 without changing failure classification or log severity.
The composition root already centralizes startup failures in StartupFailures and runtime warning
frames in RuntimeWarnings. The remaining scheduler/decorator log sites must use the same principle:
human-readable text may vary, but operator-facing dimensions use stable structured field names.
## Rules
- startup failures use `startup.phase`, `error.code` and `error.category`;
- a root cause may add `error.root_cause.class` and `error.root_cause.message`;
- runtime warnings use `warning.kind` plus bounded context such as `capability`, `operation` or `meter`;
- scheduled retry behavior is exposed as `retry.disposition` rather than embedded only in prose;
- bounded cleanup counters use `cleanup.*` fields;
- asynchronous executor rejection uses `error.code/error.category` plus `executor_name`, `policy` and
`queue_size`;
- unbounded identifiers must not become structured fields merely for convenience. In particular,
distributed-lock keys remain message text and are not emitted as `lock.key`.
No `error.code` is invented for the outbox scheduler's catch-all failure because that exception may
come from claim, status transition, metrics refresh or another relay-cycle concern. It is not
necessarily an `OUTBOX_PUBLISH_FAILED` event.
## Verification
`BootstrapStructuredRuntimeLoggingTest` captures real Logback events and checks the structured
argument set for fileserver cleanup success/failure, outbox relay catch-all retry and lock lease
expiry.
## Verified result
- BootstrapStructuredRuntimeLoggingTest: PASS;
- app-bootstrap Spotless, full test and architectureTest: PASS;
- production WARN/ERROR scan found zero candidates without structured kv/v arguments;
- docs/observability/log-fields.md is the field-name/cardinality SSOT;
- git diff --check: PASS.