rust-error-observability

Rust エラーオブザーバビリティ

このスキルを使って、ユーザー向けの応答を安全に保ちながら、Rust サービスの障害を運用担当者が理解しやすくします。エラー処理とテレメトリを、ひとつの設計領域として扱います。

基本的なワークフロー

1. エラーの流れを洗い出します。ハンドラーの戻り値の型、サービス／リポジトリのエラー、ワーカーのエラー、ミドルウェア、ログ、トレーシングの設定を確認します。
2. エラーを目的別に分類します。
   • ドメインまたはバリデーションの結果。
   • 復旧可能な制御フロー。
   • 運用担当者向けの診断情報。
   • ユーザー向けの HTTP 応答。
3. ドメインエラーは型付きのままにします。呼び出し元でパターンマッチする想定のエラー分岐には、thiserror を使います。
4. インフラストラクチャ境界でコンテキストを追加します。呼び出し元で依存関係の障害すべてをパターンマッチする必要がない場合は、anyhow または不透明なアプリケーションエラーを使います。
5. 各フレームワークで、エラーを HTTP 応答に変換する場所をひとつにまとめます。ResponseError、Axum の IntoResponse、または小規模なアダプター関数を使います。
6. ログ行を増やす前に、構造化スパンを追加します。生のペイロードやシークレットではなく、安定した診断用フィールドを含めます。
7. エラーが一度だけ記録されるようにします。リクエストのコンテキストを利用できる外側の境界でログを記録するのがおすすめです。
8. 動作を変更した場合は、公開レスポンスと診断経路の両方をテストします。

エラー境界のルール

• ドメインモジュールは、HTTP ステータスコードではなくドメインエラーを返します。
• リポジトリモジュールはクエリや操作のコンテキストを追加しますが、エラーを逐一ログに記録しません。
• ハンドラーはドメインの結果をレスポンス型に変換し、予期しない障害は一貫した 500 エラーとして扱います。
• バックグラウンドワーカーは、失敗したジョブ ID、試行回数、次のアクションをログに記録します。
• 不変条件がその場で成立し、パニックメッセージが役立つ場合を除き、サービスの処理経路では unwrap、expect、または文字列ベースの map_err を避けます。

thiserror、anyhow、不透明なエラー、フレームワークのレスポンスアダプターから選ぶ際は、references/error-boundaries.md をお読みください。

トレーシングのルール

• 境界で、リクエストハンドラー、サービスメソッド、外部クライアント、データベース操作、ワーカージョブに計装を追加します。
• リクエストボディ、プール、クライアント、パスワード、トークン、大きな値には #[tracing::instrument(skip(...))] を使います。
• 安全な場合は、リクエスト ID、ユーザー ID、テナント ID、ジョブ ID、上流サービス名、冪等性キーなどのフィールドを追加します。
• シークレット、Cookie、パスワードハッシュ、ベアラートークン、個人を特定できる情報（PII）全体をログに記録しないでください。

スパン、サブスクライバーの設定、テスト時のログについては、references/tracing.md をお読みください。 シークレットを含む値を扱う前に、references/secrets-and-pii.md をお読みください。

HTTP レスポンスのパターン

レスポンスエラーは安定した意図的なものにします。

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,
        }
    }
}

レスポンス本文はユーザーにとって安全なものにします。トレースイベントには、運用担当者が必要とする診断コンテキストを含めます。

参照ファイル

• references/error-boundaries.md：エラー型とレスポンスアダプターの選び方。
• references/tracing.md：スパン、フィールド、サブスクライバーの設定、テスト出力。
• references/secrets-and-pii.md：シークレットや機微なユーザーデータのマスキングルール。