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

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.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.