1.9 KiB
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.codeanderror.category; - a root cause may add
error.root_cause.classanderror.root_cause.message; - runtime warnings use
warning.kindplus bounded context such ascapability,operationormeter; - scheduled retry behavior is exposed as
retry.dispositionrather than embedded only in prose; - bounded cleanup counters use
cleanup.*fields; - asynchronous executor rejection uses
error.code/error.categoryplusexecutor_name,policyandqueue_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.