Observability and Failure
Observability rules cover owned logging boundaries, durable failure visibility, diagnostic context, failure states, and safe telemetry retention.
Failures, logs, diagnostics, telemetry, and repair context.
7 rules
Distinguish Failure StatesOBSERVABILITY-DISTINGUISH-FAILURE-STATESPreserve status distinctions that change recovery, messaging, metrics, or debugging. Collapsing timeouts, denials, aborts, partial work, and failures makes callers guess.Keep Diagnostics Retention SafeOBSERVABILITY-KEEP-DIAGNOSTICS-RETENTION-SAFEMatch diagnostic detail to its audience and retention period. Redact or summarize sensitive values while preserving enough operation context to debug.Keep Recovery Advice Safe and HonestOBSERVABILITY-KEEP-RECOVERY-ADVICE-SAFE-AND-HONESTGive recovery advice only when the program knows enough to make it safe. Report observed facts, label uncertainty, and avoid destructive, security-weakening, or policy-bypassing next steps unless the current state proves they are appropriate.Log at Owned BoundariesOBSERVABILITY-LOG-AT-OWNED-BOUNDARIESEmit logs where the code still knows the operation, intent, input class, and external boundary. That placement gives useful context without duplicating noise through every layer.Match Failure Output To SurfaceOBSERVABILITY-MATCH-FAILURE-OUTPUT-TO-SURFACEChoose a failure-output surface that lets the affected user notice, understand, and act on the failure. Inline errors, alerts, toasts, banners, persistent status, CLI stderr, API responses, and support artifacts have different affordances and failure modes.Preserve Operation Context in ErrorsOBSERVABILITY-PRESERVE-OPERATION-CONTEXT-IN-ERRORSCarry the operation, resource, provider, input class, and policy context that explain a failure. Stable identifiers and sanitized summaries shorten debugging without exposing payloads.Surface Durable FailuresOBSERVABILITY-SURFACE-DURABLE-FAILURESGive persistent failures a stable status, error surface, or retry path instead of only an ephemeral UI log. Users and maintainers need something actionable after the moment passes.