Observability
Logs, diagnostics, and durable failure signals at the boundary that owns them.
20 items in this guidance cluster.
Tagged guidance
Guide item
Boundary rules
Report Provider DiagnosticsBOUNDARY-REPORT-PROVIDER-DIAGNOSTICSReturn freshness, permission, budget, load, cache, partial-result, and degradation signals with provider-backed data. These diagnostics help callers decide trust, retry, display, and support behavior without exposing unactionable internals.Track Dynamic Registration ProvenanceBOUNDARY-TRACK-DYNAMIC-REGISTRATION-PROVENANCEStore stable source names, versions, paths, owners, or generated identifiers for extension, guest, generated-code, and config registrations. Provenance makes conflicts and failures diagnosable while avoiding sensitive source details.
Observability 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.
Rust rules
Implement Standard Traits for Public ErrorsRUST-IMPLEMENT-STANDARD-TRAITS-FOR-PUBLIC-ERRORSMake reusable public errors implement the standard diagnostic traits where appropriate. This lets callers compose, display, chain, and inspect errors in ordinary Rust workflows.Preserve Error ContextRUST-PRESERVE-ERROR-CONTEXTWrap and model errors so callers can see the operation, relevant input, source cause, and recovery signal. Avoid flattening failures into broad strings or generic variants that remove actionable context.Write Actionable Error DisplayRUST-WRITE-ACTIONABLE-ERROR-DISPLAYWrite Display messages that tell humans what failed and what useful next action or context exists. Keep structured state in error fields, sources, diagnostics, or Debug instead of dumping internals into the user-facing string.
Pattern items
Avoid Secret Or Private Log Contextavoid-secret-or-private-log-contextDiagnostics can outlive their request and move through systems with different access rules. Record safe identifiers and classifications at the boundary that understands data sensitivity, using explicit protected workflows for rare sensitive evidence.Contain Observability Policycontain-observability-policyLogging, metrics, tracing, and privacy choices become inconsistent when every call site invents its own policy. Put observability decisions at owned boundaries so lower layers expose facts without duplicating policy.Log At Owned Boundarieslog-at-owned-boundariesLogs become noisy and inconsistent when every helper records the same failure from a partial viewpoint. Log where the code owns the operation and can attach useful, safe diagnostic context.Make Failures Observablemake-failures-observableErrors without diagnostic context force future readers and operators to rediscover what failed. Preserve typed errors while adding operation context, correlation, metrics, or logs at the boundary that owns the meaning.Make Runtime State Agent Legiblemake-runtime-state-agent-legibleAgents can only validate behavior reliably when the relevant runtime state is observable through their tools. Expose the smallest useful signal first, such as app boot, UI inspection, logs, metrics, screenshots, traces, or generated artifacts.Preserve Error Contextpreserve-error-contextErrors often lose the facts a caller needs when they cross module, process, support, or user boundaries. Preserve stable kinds and actionable context so callers can retry, report, recover, or correlate the failure without parsing generic text.Test Observable Behaviortest-observable-behaviorTests that pin private structure can block useful refactors while missing broken user outcomes. Test observable outputs, errors, side effects, state, events, and boundaries, reserving private tests for dense rules that are otherwise hard to reach.