observability: deep-agent 出问题时 5 分钟内能定位——run 级诊断包 + 日志可拉取 + 内核假死自愈
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 7m
- Merged PRs (30d)
- 969
Description
## 背景(2026-09-07 00:15-02:30 devapp 实测)
devapp 上 deep-agent 容器(`deep-agent-service:a6c7c4b6`,17:16Z 启动)对 `POST /threads` 不响应:`live-evidence` 探针第一条 curl 挂满 15 分钟被取消;用户侧所有 run 永远「模型正在思考…」。与此同时**没有任何通道能看到它的日志**:`real-model-chat-evidence` 的 collect 步骤拿到的 journalctl 是「not seeing messages from other users」、docker logs 空(runner 用户无权限);deep-agent 没有 docker HEALTHCHECK,假死不会被重启;`backend-gates` 没有 workflow_dispatch,无法手动触发重部署。定位只能靠人类上 VM。
## 要做的(按收益排序)
1. **run 级诊断包(agent 5 分钟内可读)**:`GET /agent-runs/:id/diagnostics`(org-admin)返回 steps + failure codes + heartbeat_at + remote_run_id + 远端 thread 的 status/next/interrupts/最近 5 条消息摘要(脱敏);前端「运行详情」tab 加「复制诊断包」;一条 `agent-run-diagnose` workflow(输入 runId/threadId)把同样内容 + 该时间窗的 API journal / deep-agent docker logs / OTel trace 片段打成 artifact。
2. **日志可拉取**:runner 用户加入 `systemd-journal` 与 `docker` 组(人类 root 一次性动作,写进 `new-environment-bringup.md`);deep-agent 容器启用 `DEEP_AGENT_OTEL_TRACE_FILE=/opt/workspacex/logs/deep-agent-trace.jsonl`(每个 run 的 llm/tool span 与耗时,本地已验证可用)并 logrotate;API 每条 run 生命周期日志带 runId/threadId/remoteRunId 结构化字段。
3. **内核假死自愈**:deep-agent 加 docker `HEALTHCHECK`(真调一次 `POST /threads` + 5s 超时,不是 /ok),`--restart` 配合 unhealthy 自动重启;API 的 `checkKernelHealth` 同样用带超时的真实探测,探测不过 ⇒ 新 run 立即 KERNEL_UNAVAILABLE 而不是排队等死。
4. `backend-gates` 加 `workflow_dispatch`,让人/agent 能手动重部署当前 main。
## 验收
- 本地复现"内核假死"(kill -STOP deep-agent):60s 内容器被重启;期间新 run 立即 KERNEL_UNAVAILABLE;诊断包能显示该 run 的 heartbeat 与远端状态。
- devapp 上跑一次 `agent-run-diagnose` workflow,artifact 里三类日志非空。
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the existing run-detail API, checkKernelHealth entry point, and frontend “运行详情” tab, then inspect backend-gates and new-environment-bringup.md. Map the diagnostics endpoint, workflow inputs, container health check, and logging changes before choosing a focused part. Done means the kill-STOP reproduction recovers within 60 seconds, new runs fail with KERNEL_UNAVAILABLE, and the diagnostic artifact contains all three log classes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, github-actions, typescript
- Domain
- backend-api-design, ci-cd, devops, frontend, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100