54 lines
2.5 KiB
Markdown
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.
|