debug

デバッグ

目標

• 実行が停止したり、再試行を繰り返したり、失敗したりする原因を特定します。
• Linear の課題 ID と Codex セッションをすばやく関連付けます。
• 根本原因を切り分けるため、適切なログを適切な順序で確認します。

ログソース

• 主なランタイムログ：log/symphony.log
  • デフォルトは SymphonyElixir.LogFile（log/symphony.log）から取得されます。
  • オーケストレーター、エージェントランナー、Codex app-server のライフサイクルログが含まれます。
• ローテーション済みランタイムログ：log/symphony.log*
  • 対象の実行が古い場合は、これらを確認します。

相関キー

• issue_identifier：人が読む課題キー（例：MT-625）
• issue_id：Linear の UUID（安定した内部 ID）
• session_id：Codex のスレッドとターンの組み合わせ（<thread_id>-<turn_id>）

elixir/docs/logging.md では、課題／セッションのライフサイクルログにこれらのフィールドが必須とされています。デバッグ時の結合キーとして使用してください。

クイックトリアージ（実行の停止）

1. 対象の課題について、スケジューラー／ワーカーに現れている症状を確認します。
2. 課題の最近のログ行を探します（まず issue_identifier を使用します）。
3. 一致する行から session_id を抽出します。
4. 開始、ストリーム、完了／失敗、停止処理の各ログで、その session_id を追跡します。
5. 失敗の種類を判断します：タイムアウト／停止、app-server の起動失敗、ターンの失敗、またはオーケストレーターの再試行ループ。

コマンド

# 1) Narrow by ticket key (fastest entry point)
rg -n "issue_identifier=MT-625" log/symphony.log*

# 2) If needed, narrow by Linear UUID
rg -n "issue_id=<linear-uuid>" log/symphony.log*

# 3) Pull session IDs seen for that ticket
rg -o "session_id=[^ ;]+" log/symphony.log* | sort -u

# 4) Trace one session end-to-end
rg -n "session_id=<thread>-<turn>" log/symphony.log*

# 5) Focus on stuck/retry signals
rg -n "Issue stalled|scheduling retry|turn_timeout|turn_failed|Codex session failed|Codex session ended with error" log/symphony.log*

調査の流れ

1. 課題に該当するログを特定します：
   • issue_identifier=<KEY> で検索します。
   • ノイズが多い場合は、issue_id=<UUID> も追加します。
2. タイムラインを組み立てます：
   • 最初の Codex session started ... session_id=... を特定します。
   • 続いて、Codex session completed、ended with error、またはワーカー終了の行を追跡します。
3. 問題を分類します：
   • 停止ループ：Issue stalled ... restarting with backoff。
   • app-server の起動：Codex session failed ...。
   • ターンの実行失敗：turn_failed、turn_cancelled、turn_timeout、または ended with error。
   • ワーカーのクラッシュ：Agent task exited ... reason=...。
4. 影響範囲を検証します：
   • 失敗が単一の課題／セッションに限られるのか、複数の課題で繰り返し発生しているのかを確認します。
5. 証拠を記録します：
   • タイムスタンプ、issue_identifier、issue_id、session_id を含む重要なログ行を保存します。
   • 推定される根本原因と、正確に失敗した段階を記録します。

Codex セッションログの読み方

Symphony では、Codex セッションの診断情報は log/symphony.log に出力され、session_id をキーとして記録されます。次のライフサイクルとして読み取ります：

1. Codex session started ... session_id=...
2. 同じ session_id に対するセッションのストリーム／ライフサイクルイベント
3. 終了イベント：
   • Codex session completed ...、または
   • Codex session ended with error ...、または
   • Issue stalled ... restarting with backoff

特定のセッションを調査する場合は、追跡対象を絞り込みます：

1. 課題の session_id を 1 つ取得します。
2. そのセッションだけを対象とする、タイムスタンプ付きのログ範囲を作成します：
   • rg -n "session_id=<thread>-<turn>" log/symphony.log*
3. 失敗した正確な段階を特定します：
   • ストリームイベントより前の起動失敗（Codex session failed ...）。
   • ストリームイベント後のターン／ランタイムの失敗（turn_*／ended with error）。
   • 停止からの復旧（Issue stalled ... restarting with backoff）。
4. 近くの行にある issue_identifier と issue_id を調査結果に照合し、並行する再試行を混同していないことを確認します。

並行する実行を混同しないよう、セッションの調査結果は必ず issue_identifier／issue_id と照合してください。

注意事項

• 大きなログをすばやく検索するには、grep より rg を優先してください。
• データが欠落していると結論付ける前に、ローテーション済みログ（log/symphony.log*）を確認してください。
• 新しいログ文に必須のコンテキストフィールドが欠けている場合は、elixir/docs/logging.md の規約に合わせてください。