rust-error-observability
Use when adding, changing, debugging, or reviewing Rust service error handling and observability, especially when separating domain errors from HTTP responses, adding thiserror/anyhow, implementing ResponseError or IntoResponse, adding tracing spans, redacting secrets, or diagnosing async failures.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- rust-error-observability
- license
- MIT
- metadata
- { "tags": "rust,error-handling,observability,tracing,backend", "version": "0.1.0", "category": "Rust", "displayName": "Rust Error Observability" }
- description
- Use when adding, changing, debugging, or reviewing Rust service error handling and observability, especially when separating domain errors from HTTP responses, adding thiserror/anyhow, implementing ResponseError or IntoResponse, adding tracing spans, redacting secrets, or diagnosing async failures.
- compatibility
- Codex, Claude Code, and other Agent Skills-compatible clients.
02 资源文件 4
- 参考文档agents/openai.yaml205 B
- 参考文档references/error-boundaries.md2.1 KB
- 参考文档references/secrets-and-pii.md1.4 KB
- 参考文档references/tracing.md2.0 KB
03 SKILL.md 正文
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
- Inventory error flows: handler return types, service/repository errors, worker errors, middleware, logs, and tracing setup.
- Classify each error by purpose:
- Domain or validation outcome.
- Recoverable control flow.
- Operator diagnostic.
- User-facing HTTP response.
- Keep domain errors typed. Use
thiserrorfor expected branches that callers should match on. - Add context at infrastructure boundaries. Use
anyhowor opaque application errors when callers should not match every dependency failure. - Map errors to HTTP responses in one place per framework:
ResponseError, AxumIntoResponse, or a small adapter function. - Add structured spans before more log lines. Include stable diagnostic fields, not raw payloads or secrets.
- Ensure errors are logged once. Prefer logging at the outer boundary where request context is available.
- 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 stringlymap_errin 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.
Tracing Rules
- Instrument request handlers, service methods, outbound clients, database operations, and worker jobs at boundaries.
- Use
#[tracing::instrument(skip(...))]for request bodies, pools, clients, passwords, tokens, and large values. - Attach fields like request ID, user ID, tenant ID, job ID, upstream name, and idempotency key when safe.
- Do not log secrets, cookies, password hashes, bearer tokens, or full PII.
Read references/tracing.md for spans, subscriber setup, and test logging.
Read references/secrets-and-pii.md before touching secret-bearing values.
HTTP Response Pattern
Keep response errors stable and intentional:
pub enum SubscribeError {
Validation(SubscribeValidationError),
Unexpected(anyhow::Error),
}
impl actix_web::ResponseError for SubscribeError {
fn status_code(&self) -> actix_web::http::StatusCode {
match self {
Self::Validation(_) => actix_web::http::StatusCode::BAD_REQUEST,
Self::Unexpected(_) => actix_web::http::StatusCode::INTERNAL_SERVER_ERROR,
}
}
}
The response body should be safe for users. The trace event should carry the diagnostic context operators need.
Reference Files
references/error-boundaries.md: choosing error types and response adapters.references/tracing.md: spans, fields, subscriber setup, and test output.references/secrets-and-pii.md: redaction rules for secrets and sensitive user data.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.