stacktrace-log-triage

スタックトレースのログトリアージ

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-15）に由来する Tier 1 の重要スキルです。

ミッション

ノイズの多い障害の証拠を、信頼度を明示した診断結果として順位付けします。 症状、直接の原因、真の根本原因を必ず区別します。

まず証拠を収集する

• 最上位のフレームだけでなく、スタックトレース全体を読みます。
• 最初の障害の前後にあるログ行を読みます。
• タイムスタンプ、相関 ID、リクエスト ID、スレッド名、有効なプロファイルを、取得可能な場合は記録します。
• 入手可能であれば、関連する最近のコードや設定の変更を確認します。
• 可能であれば、project-context-ingestion のリポジトリ制約を再利用します。

トリアージのワークフロー

1. 最も早い、意味のある障害シグナルを特定します。
2. Caused by: の連鎖を、これ以上具体的な原因が現れなくなるまでたどります。
3. インシデントを分類します。
   • DI とコンテキストの起動
   • 設定のバインディング
   • シリアライズまたは検証
   • SQL またはマイグレーション
   • HTTP またはタイムアウト
   • セキュリティ
   • 並行処理またはロック
   • クラスパスまたはバージョンの不一致
4. 何が失敗したのかと、なぜ失敗したのかを切り分けます。
5. 証拠が不十分な場合は、仮説に順位を付けます。
6. 迅速な緩和策と適切な修正策を分けて提案します。

診断ルール

• BeanCreationException、InvocationTargetException などのラッパー例外は、診断結果ではなく伝達手段として扱います。
• フレームワークのラッパーの後に続く、最初のユーザーコードのフレームを重要な証拠として扱います。
• スタックの深さだけでなく、ログの時系列を利用します。
• ログが途中で切れている場合はその旨を伝え、信頼度を下げます。
• 記憶に基づくパターン照合よりも、観測されたコードパスや設定に基づく説明を優先します。

高度なシグナルパターン

• 抑制された例外、スタックトレースの1～2行上にある根本原因のログ出力、隣接するスレッドで発生している関連障害を確認します。最も有用な手掛かりは、メインのスタックに現れないことがよくあります。
• 重大な障害と、飽和状態のパターンを区別します。接続プールの枯渇、スレッドプールの枯渇、イベントループのブロッキング、リトライストーム、デッドロックの再試行は、二次的な症状として先に現れることがよくあります。
• SQL の障害では、取得可能な場合はベンダーコードと SQL の状態を確認します。ラッパー例外の型よりも、問題の特定に役立つことがよくあります。
• バージョン変更やデプロイ後の起動障害では、コードのバグを疑う前に、クラスパスと設定の差異を比較します。
• 間欠的な障害では、時間的な相関と並行処理の状況を重視します。競合状態では、単一スレッドの明快な経緯が残ることはまれです。
• OOM または GC 関連のインシデントでは、通常のスタックトレースだけでは証拠として不十分です。スレッドダンプ、ヒープの症状、割り当ての状況がより重要です。
• メトリクスがある場合は、ログを個別に扱うのではなく、最初のエラー急増をレイテンシ、プールの飽和、または下流依存先の劣化と関連付けます。
• リアクティブコードやコルーチンのコードで症状が現れる場合は、ID の欠落や誤解を招くスレッド名を問題視する前に、コンテキスト伝播が途切れてログの相関が失われていないか確認します。

専門家向けヒューリスティクス

• トリアージ後の最初の修正では、問題の緩和だけでなく、不確実性の低減も目指します。診断の精度も高められる緩和策を優先します。
• 複数の原因候補が当てはまる場合は、証拠、影響範囲、提案する緩和策の可逆性に基づいて順位を付けます。
• トレースがフレームワークのラッパーを示している場合は、最近変更されたコードや設定へ外側に向かって調べ、そこから因果関係の連鎖を内側へたどります。
• 主要な仮説を覆す証拠を必ず明示します。

出力仕様

次のセクションを返します。

• Root cause：確認済み、または最も可能性の高い原因を平易な言葉で説明します。
• Confidence：confirmed、high、medium、low のいずれかです。
• Evidence：診断を裏付けるログ行、例外、設定上の事実、またはコードパスです。
• Hotfix：最も安全な即時の封じ込め策、またはブロックを解除する手順です。
• Long-term fix：適切なコードまたは設定の修正です。
• Reproduction and verification：修正を再現、テスト、監視する方法です。

安全ルール

• 仮説は仮説として明示してください。
• インシデントによって本当に安全な選択肢がほかにない場合を除き、リスクの高いスキーマ変更、バージョンアップ、広範なリファクタリングを緊急修正として推奨しないでください。
• ログが不完全な場合は、確実であると断言しないでください。
• 修正後のアラートやモニタリングへの影響を見落とさないでください。

Kotlin 固有の確認事項

• プラットフォーム型による NullPointerException に注意してください。
• 元の呼び出し経路が分かりにくくなるコルーチンのスタックトレースに注意してください。
• Kotlin コンパイラープラグインの不足によって、実行時の動作に不備が生じていないか確認してください。
• Jackson と Kotlin のコンストラクターに関する問題が、一般的なデシリアライズエラーとして表面化していないか確認してください。

品質基準

このスキルの適切な実行では、ユーザーが障害の証拠から安全な修正に至る道筋を示します。 不適切な実行では、最上位の例外を繰り返し、Caused by: の連鎖を無視するか、リスクを説明せずに危険な緊急修正を提案します。