--- name: log-debugger description: | システムログを分析してエラーの根本原因を特定し、段階的に深堀りしていくデバッグ専門家スキル。 アプリケーションログ、システムログ、クラウドサービスログなど様々な形式に対応。 5 Whys、タイムライン分析、Fishbone分析などのRCA（根本原因分析）手法を用いて 問題の本質を突き止め、再発防止策まで提案する。 Use when analyzing system logs to find error root causes, debugging application issues, or performing technical post-mortem analysis with log data. For organizational incident management processes (post-incident review, corrective action plans, incident reports without log data), use incident-rca-specialist instead. Triggers: "analyze this log", "find the root cause", "debug this error", "why is this failing", "log analysis", "what caused this crash", "troubleshoot this issue" --- # Log Debugger ## When to Use Use this skill when: - **Debugging application crashes** - analyzing stack traces, exceptions, and error logs - **Investigating production incidents** - finding root cause from system/application logs - **Troubleshooting intermittent issues** - identifying patterns in recurring errors - **Performing post-mortem analysis** - reconstructing timeline of events from logs - **Analyzing timeout or performance issues** - correlating logs across services - **Processing multi-source logs** - correlating events from app, web server, and database logs **DO NOT use** for organizational incident management (post-incident reviews, corrective action plans without log data) - use `incident-rca-specialist` instead. --- ## Prerequisites - **Python 3.8+** with standard library - **Optional**: `pyyaml` for custom configuration files - **Log files** in supported formats (plain text, JSON, syslog) --- ## Workflow 1. **Provide log data** - File path, paste content, or stdin 2. **Triage** - Claude identifies error severity and impact 3. **Pattern Recognition** - Detects error patterns and frequency 4. **Root Cause Analysis** - Applies 5 Whys, timeline, or Fishbone analysis 5. **Resolution** - Provides fix recommendations and prevention strategies --- ## Output - **Summary Report** - Error counts, severity breakdown, affected time ranges - **Timeline** - Chronological sequence of significant events - **Top Error Patterns** - Most frequent errors with normalized messages - **Root Cause Analysis** - 5 Whys or Fishbone diagram identifying root cause - **Recommendations** - Immediate fixes and long-term prevention strategies - **RCA Report** - Full report using `assets/rca_report_template.md` --- ## Overview このスキルは、システムログを体系的に分析し、エラーの根本原因を特定するデバッグ専門家です。 **対応ログタイプ:** - アプリケーションログ（Python/Java/Node.js例外、スタックトレース） - システムログ（Linux syslog, journald, Windows Event Log） - クラウドサービスログ（AWS CloudWatch, Azure Monitor, GCP Logging） - Webサーバーログ（Apache, Nginx） - Kubernetesログ ## 4-Phase Analysis Framework ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Phase 1: TRIAGE（トリアージ） │ │ 「何が起きているのか？」 │ │ └─ ログ概要把握、エラー重要度判定、影響範囲の特定 │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 2: PATTERN RECOGNITION（パターン認識） │ │ 「どのようなパターンがあるか？」 │ │ └─ エラーパターン特定、関連イベント抽出、時系列整理 │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 3: ROOT CAUSE ANALYSIS（根本原因分析） │ │ 「なぜ起きたのか？」 │ │ └─ 5 Whys分析、タイムライン再構築、因果関係特定 │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 4: RESOLUTION & PREVENTION（解決と再発防止） │ │ 「どう直し、どう防ぐか？」 │ │ └─ 修正提案、再発防止策、監視強化ポイント │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## Phase 1: Triage（トリアージ） ### 目的 ログの全体像を把握し、問題の重要度と影響範囲を素早く判断する。 ### 手順 1. **ログの取り込みと正規化** ```bash # log_analyzer.pyを使用してログを解析 python scripts/log_analyzer.py analyze --summary ``` 2. **エラーレベルの集計** - FATAL/CRITICAL: 即時対応が必要 - ERROR: 調査が必要 - WARN: 監視対象 - INFO/DEBUG: 参考情報 3. **影響範囲の特定** - 影響を受けたユーザー数/リクエスト数 - 影響を受けたサービス/コンポーネント - 発生時間帯と継続時間 ### チェックリスト ```markdown □ ログの時間範囲を確認 □ エラー件数を集計 □ 最も深刻なエラーを特定 □ 影響範囲を推定 □ 緊急度を判定（P0/P1/P2/P3） ``` --- ## Phase 2: Pattern Recognition（パターン認識） ### 目的 エラーのパターンを識別し、関連するイベントを抽出する。 ### 手順 1. **エラーパターンの検出** ```bash # エラーキーワードで検索 python scripts/log_analyzer.py search --keywords "Exception,Error,Failed,Timeout" # 正規表現でパターン検出 python scripts/log_analyzer.py search --pattern "Connection.*refused|timeout.*\d+ms" ``` 2. **頻度分析** ```bash # エラー頻度レポート python scripts/log_analyzer.py report --frequency ``` 3. **時系列パターンの確認** - 特定時刻に集中しているか - 周期的に発生しているか - 漸増/急増しているか ### パターン分類 | パターン | 特徴 | 典型的な原因 | |----------|------|--------------| | 突発的 | 特定時刻に急増 | デプロイ、設定変更、外部障害 | | 周期的 | 一定間隔で発生 | cron、バッチ処理、リソース枯渇 | | 漸増型 | 徐々に増加 | メモリリーク、ディスク枯渇 | | 散発的 | ランダムに発生 | 競合状態、間欠的な外部障害 | ### 参照 - `references/log_patterns.md` - よくあるエラーパターン集 --- ## Phase 3: Root Cause Analysis（根本原因分析） ### 目的 問題の根本原因を特定する。表面的な症状ではなく、本質的な原因を突き止める。 ### 手法1: 5 Whys分析 **プロセス:** 1. 現象を明確に記述 2. 「なぜ？」を5回繰り返す 3. 各回答を検証可能な形で記録 **例:** ``` 現象: APIが500エラーを返している 1. なぜ？ → データベースクエリがタイムアウトしている 2. なぜ？ → 特定のテーブルへのクエリが遅い 3. なぜ？ → テーブルにインデックスがない 4. なぜ？ → 新しいカラムを追加した際にインデックスを作成しなかった 5. なぜ？ → スキーマ変更時のインデックス確認プロセスがなかった → 根本原因: スキーマ変更時のレビュープロセスの不備 ``` ### 手法2: タイムライン分析 ```bash # タイムライン生成 python scripts/log_analyzer.py timeline --from "2025-01-01 10:00" --to "2025-01-01 12:00" ``` **タイムライン作成手順:** 1. 関連するすべてのログソースを収集 2. タイムスタンプで統合・ソート 3. 重要イベントをマーク 4. 因果関係を推論 ### 手法3: Fishbone（特性要因図）分析 6つのカテゴリで原因を分析: - **People**: 人的要因（操作ミス、知識不足） - **Process**: プロセス要因（手順の不備、承認漏れ） - **Technology**: 技術要因（バグ、設計ミス） - **Environment**: 環境要因（インフラ、ネットワーク） - **Data**: データ要因（不正データ、データ量） - **External**: 外部要因（サードパーティ障害） ### 参照 - `references/rca_methodology.md` - 根本原因分析手法の詳細 --- ## Phase 4: Resolution & Prevention（解決と再発防止） ### 目的 問題を解決し、同様の問題の再発を防ぐ。 ### 解決策の策定 1. **応急処置 (Immediate Fix)** - 影響を最小化する一時的な対応 - ロールバック、リスタート、回避策 2. **恒久対策 (Permanent Fix)** - 根本原因を解消する本質的な修正 - コード修正、設計変更、プロセス改善 ### 再発防止策 1. **検知の強化** - アラート追加 - ログレベル調整 - メトリクス追加 2. **防止の強化** - バリデーション追加 - テスト追加 - レビュープロセス強化 3. **復旧の強化** - ランブック整備 - 自動復旧機構 - フェイルオーバー設定 ### 出力 - `assets/rca_report_template.md` を使用してRCAレポートを作成 --- ## Scripts ### log_analyzer.py ログ解析を自動化するPythonツール。 **基本的な使い方:** ```bash # エラー検出 python scripts/log_analyzer.py analyze # キーワード検索 python scripts/log_analyzer.py search --keywords "timeout,error" # タイムライン生成 python scripts/log_analyzer.py timeline # レポート生成 python scripts/log_analyzer.py report --output report.md # 複数ログの相関分析 python scripts/log_analyzer.py correlate app.log nginx.log db.log ``` **設定ファイル:** `assets/analyzer_config_template.yaml` をコピーしてプロジェクト固有の設定を行う。 --- ## Resources ### References | ファイル | 用途 | |----------|------| | `references/rca_methodology.md` | 5 Whys、Fishbone等のRCA手法 | | `references/log_patterns.md` | よくあるエラーパターン集 | | `references/log_format_guide.md` | 各種ログフォーマット解説 | | `references/debugging_strategies.md` | デバッグ戦略・思考法 | ### Assets | ファイル | 用途 | |----------|------| | `assets/rca_report_template.md` | RCAレポートテンプレート | | `assets/analyzer_config_template.yaml` | log_analyzer.py設定テンプレート | --- ## Usage Examples ### 例1: アプリケーションクラッシュの調査 ``` User: このログを分析して、アプリがクラッシュした原因を見つけてください。 [ログファイルを添付] Claude: 1. [Phase 1] ログを読み込み、FAITALエラーを検出 2. [Phase 2] スタックトレースを抽出、OutOfMemoryErrorを特定 3. [Phase 3] 5 Whys分析を実施 - Why 1: OutOfMemoryError発生 - Why 2: ヒープメモリが枯渇 - Why 3: 大量のオブジェクトがGCされない - Why 4: キャッシュにサイズ制限がない - Why 5: キャッシュ設計時にメモリ管理を考慮していなかった 4. [Phase 4] 修正提案: LRUキャッシュ導入、ヒープサイズ調整 ``` ### 例2: 間欠的なタイムアウト調査 ``` User: 時々APIがタイムアウトします。ログを見てください。 Claude: 1. [Phase 1] タイムアウトエラーを抽出、頻度を確認 2. [Phase 2] 時間帯分析 → 毎時0分に集中 3. [Phase 3] タイムライン分析 → cron jobと同時刻 4. [Phase 4] 提案: バッチ処理の時間分散、コネクションプール拡大 ``` --- ## Best Practices ### Do's - 複数のログソースを突合して分析する - タイムスタンプを正確に揃える - 仮説を立てて検証する - 根本原因まで深掘りする - 再発防止策まで提案する ### Don'ts - 最初に見つけたエラーだけで判断しない - 相関関係を因果関係と混同しない - 表面的な症状への対処で終わらせない - 単一のログソースだけで結論を出さない