# Runtime Diagnostics

Runtime signals should reveal what happened, where in the business path, which request or task was affected, why a dependency slowed or failed, what protection activated, and whether recovery is progressing.

Use metrics for trend and saturation, traces for one path, and logs for event context and decisions. Do not replace aggregate metrics with high-volume logs.

## Signals

- Lifecycle: start, sanitized effective configuration, dependency initialization, readiness, stop, in-flight work, and recovery state.
- Business transitions: irreversible side effects, state changes, ACK, batch start or completion, quarantine, compensation, and degradation.
- Dependencies: call rate, success, error class, tail latency, timeout, retry, pool wait, in-flight work, and payload size.
- Protection and recovery: queue full, rate limit, concurrency rejection, circuit state, backpressure, backlog, oldest work, recovery rate, and drain estimate.

## Logging is not the business path

stdout, files, pipes, collectors, and network handlers can block. High-volume logging may use bounded asynchronous batching, but it must define queue size, record size, batch size, flush interval, writer count, full-queue policy, output failure behavior, and bounded shutdown flush.

Do not spawn unbounded tasks per log entry. Sample, aggregate, or drop lower-severity events under pressure and expose drop counts. Rate-limit repeated errors. Logging failure must not terminate the business process.

Observe the logging pipeline itself: production rate, queue depth, utilization, drops by level, writer blocking, batch latency, output errors, last success, and flush timeout.

Events requiring no loss, strong ordering, compliance evidence, or business success semantics are business data, not ordinary logs. Persist them transactionally or through a durable outbox or message path.

Use stable structured fields, avoid duplicate stack traces at every layer, protect secrets and personal data, and keep metric labels low-cardinality. Fault-test slow or unavailable sinks, full disks, error storms, queue saturation, and shutdown flush.