Rust Error Observability

Rust Error Observability

Use this skill to make Rust service failures understandable to operators while keeping user-facing responses safe. Treat error handling and telemetry as one design surface.

Core Workflow

1. Inventory error flows: handler return types, service/repository errors, worker errors, middleware, logs, and tracing setup.
2. Classify each error by purpose:
   • Domain or validation outcome.
   • Recoverable control flow.
   • Operator diagnostic.
   • User-facing HTTP response.
3. Keep domain errors typed. Use thiserror for expected branches that callers should match on.
4. Add context at infrastructure boundaries. Use anyhow or opaque application errors when callers should not match every dependency failure.
5. Map errors to HTTP responses in one place per framework: ResponseError, Axum IntoResponse, or a small adapter function.
6. Add structured spans before more log lines. Include stable diagnostic fields, not raw payloads or secrets.
7. Ensure errors are logged once. Prefer logging at the outer boundary where request context is available.
8. Test both the public response and the diagnostic path when behavior changed.

Error Boundary Rules

• Domain modules return domain errors, not HTTP status codes.
• Repository modules attach query or operation context, but do not log every error.
• Handlers convert domain outcomes into response types and let unexpected failures become a consistent 500.
• Background workers log failed job IDs, attempt counts, and next action.
• Avoid unwrap, expect, or stringly map_err in service paths unless the invariant is local and the panic message is useful.

Read references/error-boundaries.md when choosing between thiserror, anyhow, opaque errors, and framework response adapters.