40 lines
1.9 KiB
Markdown
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.
|