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

2.5 KiB

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.