リモートサーバーをトラブルシュートする

本番サーバーが調子悪い時は、数時間ではなく数分で診断が必要です。OpenCode は関連ログを読み、最近の変更と相互参照し、修正を提案できます — すべてあなたがサーバーの制御を維持しながら。

このレシピを使う場面

• サービスは稼働しているが、遅い、エラーが出る、断続的に 5xx を返す。
• ログが膨大で、どのサブシステムが原因か分からない。
• 修正を実行する必要があるが、何かを再起動する前に別の意見が欲しい。

前提条件

• ローカルマシンに OpenCode がインストールされている。
• 影響を受けるサーバーへの SSH アクセス。
• 関連するログと設定ファイルへの読み取り専用アクセス。

手順

1. 症状を正確に定義する

   1 段落で、何が問題か、いつ始まったか、何を既に除外したかを記述します。

   チェックアウトサービスは今日の 14:00 UTC から、リクエストの約 3% に対して 504 を返しています。レイテンシ p99 は 800ms から 6s に悪化しました。过去 6 時間はデプロイがありません。アプリノードの CPU とメモリは正常です。まだ何も再起動していません。

2. 関連ログを取得する

   ログの適切な範囲を取得し、異常を表面化させるよう OpenCode に依頼します。

   prod-app クラスターに SSH 接続してください（認証情報は 1Password 参照）。チェックアウトサービスの過去 2 時間の stdout と stderr を取得してください。エラーパターン、スタックトレース、異常なレイテンシスパイクを表面化させてください。通常のトラフィックは含めないでください。

3. 最近の変更と関連付ける

   デプロイがなくても、インフラの変更は依然として影響する可能性があります。

   過去 24 時間のインフラ変更（Terraform、ingress、DNS）を確認してください。各変更をレイテンシ増加のタイミングと相互参照してください。

4. 仮説を形成する

   最も可能性の高い原因と検証方法を提案するよう OpenCode に依頼します。

   ログとインフラ変更に基づき、レイテンシ増加に対する上位 3 つの仮説をランク順に並べてください。それぞれについて、支持的証拠と、確証または除外するために実行できる 1 つのコマンドを教えてください。

5. 中断せずに検証する

   最も影響の少ない検証パスを最初に使用してください。再起動に飛びつかないこと。

   # Example: check if a downstream is timing out
   curl -w '%{time_total}\n' -o /dev/null -s https://internal.api/ping

6. 最小の安全な修正を適用する

   検証後、問題を解決する最小の変更を加えます。修正がリスクがある場合は、最初にチームメイトに相談してください。

   仮説 #2 が確認されたので、最小の安全な変更を提案してください。正確なコマンド、次の 10 分間で監視すべき項目、ロールバック計画を教えてください。

7. インシデント後ノートを書く

   小さなインシデントであっても、何が起きたか、なぜ起きたか、何を変更すべきかを記録します。

   incidents/2026-06-27-checkout-504.md に 1 ページのインシデント後ノートを書いてください: タイムライン、根本原因、緩和策、1 つの予防措置（アラート、ランブック、テスト、またはリファクタ）を含めてください。

重要なプロンプト

[vault パス] の認証情報で [host] に SSH 接続してください。[サービス] ログの直近 [N 時間] を取得し、エラーパターン、スタックトレース、レイテンシ異常を表面化させてください。次に、同じ期間内のインフラ変更を確認してください。[症状] に対する上位 3 つの仮説をランク順に並べてください — 各々について、支持的証拠と 1 つの検証コマンド。破壊的なことは実行しないでください。

検証

• 明確な根本原因が特定され、文書化されている。
• 修正が適用され、メトリクスがベースラインに戻る。
• インシデント後ノートが書かれ、チームと共有されている。
• アラートが不足していた場合は、追加するためのフォローアップを起票する。

よくある落とし穴

• 最初に再起動する: 再起動は証拠を隠し、2 次インシデントを引き起こす可能性があります。常に診断してから行動する。
• 単一のログファイル: 症状は複数のログにまたがることがよくあります。明らかなものだけでなく、すべてから取得してください。
• インシデント後ノートをスキップする: 報告書がなければ、同じインシデントが 3 か月後に再発します。

関連ドキュメント

• トラブルシューティング — 一般的な OpenCode の問題とその解決方法
• TUI — サーバーを並行して作業するためのマルチセッションターミナル UI

関連レシピ

• bug-hunting — reason.remote.to-bug
• refactor-codebase — reason.remote.to-refactor
• git-commit-workflow — reason.remote.to-git

関連ドキュメント

• CLI
• ツール
• トラブルシューティング

次のステップ

• bug-hunting — next.remote.to-bug