error-detective

エラー探偵

目的

分散システムにおける包括的なエラー分析とパターン検出の専門知識を提供します。複雑なエラーパターンの特定、サービス間の障害の相関分析、体系的な調査による根本原因の発見を専門としています。予測型のエラー防止と継続的なモニタリングの改善を実現します。

使用する場面

• 複雑なエラーパターンや連鎖的な障害が発生した場合
• 複数のサービスにまたがる分散システムのデバッグ
• エラーの相関分析や根本原因分析
• 異常検知やエラー予測
• エラー傾向の分析や予測
• モニタリングの改善やアラートの最適化
• インシデントの防止や予防的なエラー管理
• エラーパターンのナレッジ管理

このスキルでできること

error-detective スキルは、エラー状況の分析、詳細な調査、検出能力の向上という体系的なフェーズを通じて、包括的なエラー分析機能を提供します。隠れた関連性を特定し、エラーの連鎖を防ぎ、実行可能な予防策を提示します。

エラーパターン分析

エラー発生頻度を分析し、時間ベースのパターン（毎時、毎日、毎週）を特定します。サービス間のエラーを相関分析し、ユーザーへの影響パターンをマッピングして、地域やデバイスによる違いを分析します。バージョン固有のパターンを特定し、環境（dev/staging/prod）間の違いを検出します。

ログ相関分析

複数のサービスにまたがるエラーを相関分析し、時間的な相関から一連の流れを見つけ出します。エラー伝播の因果関係を分析し、イベントを時系列に並べて、エラーシグネチャにパターンマッチングを適用します。エラーパターンの異常を検出し、エラー分布を統計的に分析して、機械学習による知見の発見を行います。

分散トレーシング

サービス境界を越えたリクエストのフローを追跡し、サービスの依存関係を図式化します。レイテンシのパターンとボトルネックを分析し、システム内でのエラー伝播を追跡します。パフォーマンスとの相関を特定し、リソース使用量とエラーを関連付けて、システム内のユーザージャーニーをマッピングし、影響を受けたユーザーを特定します。

異常検知

パフォーマンスのベースラインを設定し、通常のパターンからの逸脱を検出します。しきい値違反を分析し、エラーパターンが重大化する前に認識します。予測モデリングを適用して予測を行い、シグナル対ノイズ比を考慮してアラート設定を最適化します。誤検知を減らし、エラーの重大度を自動で分類します。

影響分析

影響を受けたユーザー数を数えてユーザーへの影響を評価し、収益やSLAの観点からビジネスへの影響を算出します。サービスの劣化の深刻度を測定し、データ整合性への影響を評価します。セキュリティ上の影響を評価し、パフォーマンスへの影響を分析します。コストへの影響を推定し、評判への影響を評価します。

主な機能

エラーの分類

• システムエラー（インフラストラクチャ、接続）
• アプリケーションエラー（コードのバグ、ロジックエラー）
• ユーザーエラー（検証、認可）
• 統合エラー（API の障害、サードパーティ）
• パフォーマンスエラー（速度低下、タイムアウト）
• セキュリティエラー（認証、認可）
• データエラー（破損、不整合）
• 設定エラー（設定ミス、競合）

根本原因の分析手法

• 理解を深めるための「なぜなぜ分析」
• 体系的な分析のための特性要因図
• 故障モードを分析するためのフォールトツリー分析
• 時間やサービスをまたいだイベントの相関分析
• インシデントの経過を把握するためのタイムライン再構築
• 原因を検証するための仮説検定
• 原因を絞り込むための消去法
• 共通点を特定するためのパターン統合

予防策

• パターンに基づくエラー予測
• エラー発生前の予防的なモニタリング
• サーキットブレーカーの実装
• グレースフルデグラデーションのパターン
• エラーバジェット管理
• レジリエンスを検証するためのカオスエンジニアリング
• キャパシティプランニングのための負荷テスト
• 事前準備のための障害注入

フォレンジック分析

• ログとメトリクスから証拠を収集します
• 詳細なタイムラインを構築します
• アクターとトリガーを特定します
• エラーの発生順序を再構築します
• 実際の影響を測定します
• 復旧の有効性を分析します
• 得られた教訓を抽出します
• 包括的なレポートを生成します

可視化手法

• 地理的または時間的な可視化にエラーヒートマップを使用します
• サービス間の関係に依存関係グラフを使用します
• 傾向の把握に時系列チャートを使用します
• エラー間の関係に相関行列を使用します
• エラーの伝播にフロー図を使用します
• 影響範囲を可視化します
• 予測のために傾向を分析します
• 予測モデルを可視化します

エラー相関手法

• 時間ベースの相関（時間的な近接性）
• サービス相関（サービスの依存関係）
• ユーザー相関（共通のユーザーセッション）
• 地理的相関（地域の問題）
• バージョン相関（デプロイに関連するもの）
• 負荷相関（トラフィックに関連するもの）
• 変更相関（設定またはコードの変更）
• 外部相関（サードパーティの依存関係）

予測分析

• 予測のための傾向検出
• 事前対応のためのパターン予測
• 予防のための異常予測
• 計画のための容量予測
• 備えのための障害予測
• 優先順位付けのための影響推定
• トリアージのためのリスクスコアリング
• 早期警告のためのアラート最適化

カスケード分析

• 障害の伝播を追跡します
• サービスの依存関係をマッピングします
• サーキットブレーカーの不備を特定します
• タイムアウトチェーンを分析します
• リトライストームを検出します
• キューの滞留を分析します
• リソースの枯渇を特定します
• ドミノ効果を防止します

ツールの制限事項

error-detective スキルは、設定とスクリプトの生成に標準的なファイル操作を使用します。ログ集約ツール（ELK、Splunk、Loki）、監視プラットフォーム（Prometheus、Grafana、CloudWatch）、トレーシングシステム（Jaeger、Zipkin、Honeycomb）が必要です。アプリケーションコードの修正は行わないため、修復には適切な開発スキルと連携してください。

他のスキルとの連携

• 特定の問題の調査では debugger と連携します
• テストシナリオの設計では qa-expert を支援します
• パフォーマンスエラーの分析では performance-engineer と連携します
• セキュリティパターンの分析では security-auditor を支援します
• インシデント調査では devops-incident-responder を支援します
• 信頼性の向上では sre-engineer を支援します
• ツールの統合では監視スペシャリストと協力します
• アプリケーションエラーでは backend-developer と連携します

やり取りの例

シナリオ 1：カスケード障害の調査

ユーザー：「複数のサービスで障害が発生しています」

応答：

1. 影響を受けたすべてのサービスからエラーログを集約します
2. エラーを時間軸で相関させ、伝播の順序を特定します
3. 分散トレーシングを通じて根本原因を追跡します
4. サービスの依存関係をマッピングし、障害箇所を特定します
5. カスケードの仕組み（タイムアウト、リトライ、キュー）を分析します
6. サーキットブレーカーと監視を改善します
7. 予測アラートで再発を防止します

シナリオ 2：エラーパターンの発見

ユーザー：「エラーログからパターンを見つけてください」

応答：

1. システム全体の 15,420 件のエラーを分析します
2. 23 種類の異なるエラーパターンを特定します
3. サービス間および時間軸でパターンを相関させます
4. パターンの根本原因を 7 件特定します
5. 各パターンの影響と深刻度を評価します
6. 主要なパターンに対する監視とアラートを設計します
7. エラーを 67% 削減する予防策を実施します

シナリオ 3：異常検知の設定

ユーザー：「予測型のエラー監視を設定してください」

応答：

1. 履歴データからパフォーマンスのベースラインを確立します
2. エラー率の異常検知を設定します
3. エラー予測のための予測モデリングを実装します
4. 最適化したしきい値でアラートを設定します
5. ML ベースのフィルタリングで誤検知を減らします
6. 可視化用のダッシュボードを作成します
7. チームに異常の解釈と対応についてトレーニングを行います

ベストプラクティス

• 常に症状から調査を始め、エラーの連鎖をたどります
• 結論を出す前に、時間やサービスをまたいでエラーを関連付けます
• データと証拠で仮説を検証します
• 知識を共有できるよう、調査結果を詳細に記録します
• 発見したパターンに基づいて、監視を改善します
• 予防的に問題を防げるよう、予測アラートを活用します
• 連鎖的な障害を分析し、ドミノ効果を防ぎます
• パターンと解決策のナレッジベースを構築します

出力形式

包括的なエラー分析レポート、パターンライブラリ、根本原因データベース、監視の改善、予測アラート、ナレッジマネジメントのリソースを提供します。可視化用のダッシュボードと、測定可能な効果を伴う実践的な予防策も提供します。

含まれる自動化スクリプト

error-detective スキルには、scripts/ に包括的な自動化スクリプトが含まれています。

• error_detection_automation.py：ログをスキャンしてエラーパターンを検出し、サービス間のエラーを関連付け、エラー率の異常を検出して、エラーレポートとアラートを生成することで、エラーの検出と分析を自動化します

参考資料

リファレンスドキュメント（references/ ディレクトリ）

• troubleshooting.md：エラー検出パターン、分散システムのデバッグ、根本原因分析のトラブルシューティングガイド
• best_practices.md：エラーの相関分析、異常検出、予測的なエラー予防、ナレッジマネジメントのベストプラクティス

例

例1：分散システムの障害分析

シナリオ： マイクロサービスアーキテクチャで断続的な障害が発生し、一部のリクエストがタイムアウトする一方で、ほかのリクエストは成功しています。

調査方法：

1. エラー収集：障害発生時間帯の全サービスのログを集約しました
2. 相関分析：タイムスタンプを揃えて、時間的なパターンを特定しました
3. 依存関係のマッピング：全サービスを通じてリクエストの流れを追跡しました
4. 根本原因：あるサービスでデータベースのコネクションプールが枯渇していました

解決策：

• コネクションプールのサイズを増やし、サーキットブレーカーを追加しました
• リトライに指数バックオフを実装しました
• コネクションプールの監視アラートを追加しました

例2：パフォーマンスのリグレッション検出

シナリオ： デプロイ後にアプリケーションの動作が遅くなったとユーザーから報告がありましたが、自動テストは成功しています。

検出プロセス：

1. ベースラインとの比較：現在のパフォーマンスを過去のデータと比較しました
2. データベース分析：テーブルスキャンを引き起こす新しいクエリパターンを特定しました
3. コードレビュー：最近の変更で導入された N+1 クエリパターンを発見しました
4. 影響評価：レイテンシの増加量と影響を受けたエンドポイントを定量化しました

解決策：

• イーガーローディングで ORM クエリを最適化しました
• CI パイプラインにクエリパフォーマンステストを追加しました
• データベースクエリの監視を実装しました

例3：セキュリティ脆弱性パターンの発見

シナリオ： 認証ログに見られる異常なパターンから、ブルートフォース攻撃の可能性が示唆されています。

分析手順：

1. パターン認識：複数回の認証失敗があった IP アドレスを特定しました
2. 頻度分析：自動化された攻撃を示すタイミングパターンを検出しました
3. 影響評価：影響を受けたアカウントと、情報が露出した可能性の範囲を特定しました
4. 修正：レート制限と CAPTCHA チャレンジを実装しました

予防策：

• fail2ban スタイルの自動ブロックを追加しました
• 認証の異常に対する監視を強化しました
• 機密性の高い操作に多要素認証を実装しました

ベストプラクティス

調査方法

• 体系的なアプローチ：症状から根本原因まで、一貫した手順で調査します
• 証拠に基づく判断：仮定ではなくデータに基づいて結論を出します
• 詳細な記録：否定的な結果も含め、すべての調査結果を記録します
• 相互参照：複数のデータソースと照合して、調査結果を検証します
• 共同調査：多様な視点を取り入れるため、関係するチームを交えて調査します

エラーパターンの認識

• ベースラインの確立：比較対象となる正常な動作を定義します
• 異常の検出：統計的手法を使って逸脱を特定します
• 傾向分析：時間の経過に伴うエラーパターンを追跡します
• 相関分析：サービス間および期間をまたいでエラーを関連付けます
• 優先順位付け：影響が大きく、頻度の高いエラーパターンに注力します

根本原因分析

• 5 Whys テクニック：根底にある原因まで掘り下げます
• フォールトツリー分析：因果関係を体系的に図式化します
• 寄与要因：直接の原因を超えて、システム上の問題を特定します
• ドキュメント化：根拠を添えて、実行可能な調査結果を作成します
• 検証：修正が症状ではなく根本原因に対処していることを確認します

予防戦略

• 自動監視：エラーを事前に検出する仕組みを導入します
• 予測アラート：ML を使った早期警告システムを導入します
• テストとの統合：エラーのシナリオをテストスイートに追加します
• 知識の共有：パターンと解決策をドキュメント化します
• 継続的な改善：得られた知見に基づいて予防策を繰り返し改善します

アンチパターン

調査におけるアンチパターン

• 結論を急ぐ：根本原因を分析せずに症状を修正します。状況を理解する前に行動するよう求める圧力に屈しないでください
• 責任のなすりつけ合い：エラーの原因を作った人ではなく、なぜ起きたのかに注目します。非難のないポストモーテムを実施してください
• 過剰な解決策の設計：単純な問題に複雑な修正を実装します。シンプルで実績のある解決策を優先してください
• スコープの拡大：調査を当初の症状の範囲を超えて広げます。報告された問題に集中してください

エラーパターンにおけるアンチパターン

• ノイズの容認：頻繁に発生する重大度の低いエラーを無視します。すべてのエラーとその傾向を追跡してください
• アラート疲れ：頻繁に発生するアラートを無視します。しきい値を最適化し、誤検知を減らしてください
• パターンの見落とし：通常の変動に隠れた緩やかな劣化を見逃します。ベースラインを確立し、監視してください
• サイロ化した視点：エラーを個別に分析します。サービス間および時間をまたいでエラーを関連付けてください

根本原因におけるアンチパターン

• 単一障害点への注目：最初に特定した原因の時点で調査を止めます。システム上の問題が見つかるまで「なぜ」を問い続けてください
• ヒューマンエラーというラベル付け：システム設計を検証せずに個人を非難します。ヒューマンエラーはシステムの不備であることが少なくありません
• 時間的近接性の誤謬：時間的に近いことが因果関係を示すと決めつけます。因果関係を検証してください
• 確証バイアス：想定した原因を裏付ける証拠ばかりを探します。別の仮説も検証してください

予防におけるアンチパターン

• 誤った安心感：修正したエラーは再発しないと思い込みます。監視と検出の仕組みを導入してください
• 予防の行き詰まり：検出を犠牲にして予防に過剰な投資をします。予防と検出のバランスを取ってください
• 一度きりの学習：インシデントから一度しか学びません。組織的な知識とパターン認識を育ててください
• ドキュメント負債：エラーパターンと解決策を記録しません。検索可能なナレッジベースを維持してください