production-troubleshooting

本番環境のトラブルシューティング

概要

Sentry、kubectl、Helm の設定分析を使用した体系的な調査ワークフローにより、本番／テスト環境のパフォーマンス問題やエラーを診断します。

前提条件

トラブルシューティングを始める前に、Sentry と Kubernetes ツールを利用できることを確認してください。

• 利用可能な場合は、環境を考慮したコマンドを実行できる k8s-tool を優先してください。
• k8s-tool がインストールされていないか、現在の環境で設定されていない場合は、通常の kubectl コマンドを使用してください。
• コマンドを実行する前に、ネームスペースと対象環境（test または prod）を確認してください。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• テスト／本番環境（localhost 以外）でインシデントを調査する
• エンドポイントの遅延、クエリの遅延、レイテンシの上昇をトラブルシューティングする
• Pod のクラッシュ、再起動ループ、OOMKilled、スロットリングの可能性をデバッグする
• Sentry のトレースを分析し、失敗やトランザクションの劣化を調査する
• Kubernetes のリソース制限と関連する Helm の値を検証する

調査ワークフロー

症状に基づく以下のワークフローに従い、変更を加える前に証拠を確認してください。

Step 1: 主な症状に基づくトリアージ

報告された症状に応じて、最初に行う調査を選択してください。

• Pod のクラッシュ／再起動の症状（CrashLoopBackOff、OOMKilled、頻繁な再起動）がある場合は、まず Pod のステータスとログを確認してください。
• レイテンシ／エンドポイントの遅延がある場合は、まずトレースを調べ、その後ログや Pod の状態と照合してください。

Step 2A: Pod のステータスとログを調べる（クラッシュ／再起動の経路）

Pod が中心となるインシデントでは、トレースを分析する前に Pod の正常性を確認してください。

k8s-tool を使用する場合（推奨）：

k8s-tool describe --resource pod --name <pod-name> --env <env>
k8s-tool logs --pod <pod-name> --env <env> --tail 200

kubectl を使用する場合（代替手段）：

kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --tail 200

再起動の理由、終了メッセージ、プローブの失敗、繰り返し発生する起動エラーを確認してください。

Step 2B: Sentry のトレースを調べる（レイテンシ／エラーの経路）

Sentry を使用して、データベース呼び出しの遅延、外部サービスのレイテンシ、トランザクション単位の失敗を特定してください。

Sentry MCP を使用する場合：

• 報告された問題に関連するトレースを検索します
• 遅いデータベースクエリを確認します（このプロジェクトでは、500ms 超を目安として利用できますが、すべてのケースに適用できる閾値ではありません）
• 外部 API 呼び出しのレイテンシを確認します
• エラーのパターンとスタックトレースを特定します

確認する項目：

• 想定されるベースラインを超えるデータベースクエリ時間（このプロジェクトでは一般に約500ms）
• レイテンシの高い外部 API 呼び出し
• 繰り返し発生するエラーのパターン
• パフォーマンス低下の傾向

Step 3: アプリケーションログを確認する

kubectl のログを調べて、タイミング情報とエラーのパターンを確認してください。

k8s-tool を使用する場合：

k8s-tool logs --pod <pod-name> --env <env> --tail 200

検索する主なログパターン：

• [Server] - サーバーの起動と初期化のタイミング
• [SSR] - サーバーサイドレンダリングのタイミング
• [tRPC] - TRPC クエリの実行タイミング
• [DB Pool] - データベース接続プールの状態
• ERROR または WARN - アプリケーションのエラーと警告

よくある問題：

• 並列処理（Promise.all）ではなく、API 呼び出しを順次実行している
• DB 接続の取得に時間がかかる
• SSR のレンダリングが遅い

Step 4: Pod のリソース使用量を確認する

CPU とメモリの使用量を検証し、スロットリングを検出してください。

k8s-tool を使用する場合：

k8s-tool top --env <env>

注意すべき兆候：

• CPU 使用率が 70% を超える場合、スロットリングの可能性があります
• メモリ使用率が 80% を超える場合、OOM のリスクが高まっている可能性があります
• 高い使用率が続く場合、リソースが不足している可能性があります

Step 5: Pod の設定を確認する

リソース制限と Helm の値を確認し、設定ミスを特定してください。

kubectl を使用する場合：

kubectl get pod <pod-name> -n <namespace> -o yaml

確認する主な項目：

• resources.limits.cpu と resources.limits.memory
• resources.requests.cpu と resources.requests.memory
• 環境変数の設定
• イメージのバージョンとタグ

Helm の値の場所：

• web-app：/kubernetes/helm/web-app/values.{test,prod}.yaml

Helm の設定構造の詳細については、references/helm-values-locations.md を参照してください。

Step 6: 設定を変更する前に証拠を確認する

Helm の値やコードを編集する前に、提案する修正が観測された証拠に基づいていることを確認してください。

• トレース、ログ、Pod イベント、またはリソースメトリクスから得られた具体的な証拠と、各変更を関連付けます。
• まずは、最小限で元に戻せる変更を優先します。
• デプロイ後にトレース／ログを再確認して、影響を検証します。

よくある原因と解決策

CPU／メモリのスロットリング

• 症状： CPU／メモリの使用率が高い状態が続き、応答時間が悪化したり、再起動が発生したりする
• 証拠による確認： リソースメトリクスをスロットリングの兆候、再起動イベント、レイテンシの急上昇と照合します
• 解決策： 確認後にのみ、Helm の値でリソースのリクエスト／制限を調整します

ネットワークレイテンシ

• 症状： 外部 API 呼び出しが遅い、DNS 解決に時間がかかる
• 証拠による確認： ネットワークに依存する操作の遅いスパンと時刻付きログエントリを検証します
• 解決策： ネットワークポリシーを確認し、DNS 設定を検証して、必要に応じて再試行動作を調整します

データベース接続プールの問題

• 症状： [DB Pool] エラー、接続の取得が遅い
• 証拠による確認： プールに関する警告を、トレースのタイミングと接続待ちのパターンと照合します
• 解決策： idleTimeoutMillis とプールサイズの設定を確認します

API 呼び出しの逐次実行

• 症状： 複数の API 呼び出しにかかる時間が累積する
• 証拠による確認： トレース内のスパンの逐次的な順序、またはタイムスタンプ付きログの順序を検証します
• 解決策： Promise.all() を使った並列実行にリファクタリングします

リソース

kubectl コマンド

利用可能な場合は k8s-tool で以下の一般的な操作を実行し、利用できない場合は同等の生の kubectl コマンドを代わりに実行します。

• k8s-tool logs --pod <pod> --env <env> --tail 200 - Pod のログを抽出してフィルタリングします
• k8s-tool top --env <env> - Pod の CPU／メモリ使用量を表示します
• k8s-tool describe --resource pod --name <pod> --env <env> - リソース制限と Pod の設定を確認します
• k8s-tool kubectl --env <env> --cmd "get pods" - その他の操作に生の kubectl を使用します

references/

• helm-values-locations.md - Helm の値ファイルの構造と場所に関する詳細ガイド
• common-issues.md - よくある本番環境の問題と解決策の一覧