debug

调试

目标

• 查明运行卡住、反复重试或失败的原因。
• 快速关联 Linear 问题标识与 Codex 会话。
• 按正确顺序查看日志，以定位根本原因。

日志来源

• 主要运行时日志：log/symphony.log
  • 默认路径由 SymphonyElixir.LogFile 提供（log/symphony.log）。
  • 包含编排器、Agent 运行器和 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。
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 配对，以免混淆 并发运行。

说明

• 大型日志中优先使用 rg 而不是 grep，速度更快。
• 在判断数据缺失前，请检查轮转后的日志（log/symphony.log*）。
• 如果新日志语句缺少必要的上下文字段，请遵循 elixir/docs/logging.md 中的规范。