pikasTech-unidesk/docs/MDTODO/observability-trace-reliability.md

# 可观测性与 Trace 可靠性 MDTODO

范围：长期跟踪跨服务 OTel trace context、业务 trace 与诊断 trace 隔离、Span Link、诊断重复性和 trace 证据稳定性。单个故障或 GitHub issue 作为 MDTODO ITEM 进入本文件，不为一次性 trace 或根因新建 MDTODO FILE。


## R1 [in_progress]

解决 [UniDesk #1801](https://github.com/pikasTech/unidesk/issues/1801)：隔离业务 trace 与 diagnostic trace，使诊断读取保持可观测但不再向被诊断业务 trace 补记 span；不得通过静默过滤隐藏真实 span，不改变已验收的纯 Kafka + SSE 实时/刷新链路，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1_Task_Report.md)。

### R1.1 [completed]

冻结 [#1801](https://github.com/pikasTech/unidesk/issues/1801) 的 trace-context 合同：业务 trace 只承载原业务执行证据，diagnostic trace 使用独立 traceId，并通过 OTel Span Link 和明确关联字段引用目标 trace；定义跨 UniDesk/AgentRun 的 propagation、采样、错误和兼容边界，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.1_Task_Report.md)。

### R1.2 [in_progress]

依赖 R1.1，执行 [AgentRun #302](https://github.com/pikasTech/agentrun/issues/302) 与 [UniDesk #1805](https://github.com/pikasTech/unidesk/issues/1805)：修改 request-scoped diagnostic context 与相关 instrumentation，使 command/result/events 读取不继承目标业务 trace 的 active parent，同时保留独立诊断 trace、Span Link、businessTraceId/commandId 关联和有界 CLI 可见性；禁止新增 terminal authority 或 Kafka event，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.2_Task_Report.md)。

### R1.3

依赖 R1.2，用固定 warm-session trace 验证重复诊断不改变原业务 trace 的 terminal/instrumentation 判定，诊断 trace 仍完整可查；补跨服务合同和端到端验收，确认实时、刷新回放及纯 Kafka + SSE 事件顺序均无变化，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R1.3_Task_Report.md)。

## R2 [completed]

调查第二轮业务 trace `trc_9352107b5e8a4125` / session `ses_d4473d6c-4d7a-4612-a102-254977698bc2` 的文件编辑、`apply_patch` 与 tool event 可见性：先解析对应 OTel trace/run/command，再对照 codex stdio notification、AgentRun durable events、`agentrun.event.v1`、`hwlab.event.v1` 和 HWLAB trace/read model，并使用受控的集群内或应用侧 CLI 执行 Kafka replay 校对，判定事件是源头未产生、AgentRun 映射遗漏、Kafka 转换丢失还是 HWLAB 投影丢失；不得手写 Kafka API、不得用重放追加产品 topic event、不得把投影滞后改写成业务失败，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R2_Task_Report.md)。

## R3 [completed]

解决 [UniDesk #1923](https://github.com/pikasTech/unidesk/issues/1923)：提高 CI/CD 自动链错误暴露能力并接入 OTel，覆盖 GitHub webhook→Gitea snapshot→PaC→Tekton PipelineRun/TaskRun/step→artifact/GitOps→Argo/runtime/health 的 trace context、阶段 span、首断点与脱敏错误投影；让 cicd status、PaC status/history/debug-step 和 sentinel control-plane status 默认有界显示 traceId/error code/phase/exit/下钻。exporter、版本或 commit 漂移只能非阻塞 warning；禁止新增人工交付路径、第二 authority、锁/租约/证据链/状态机，以真实失败 hwlab-web-probe-sentinel-nc01-6gjzl 和新 PR merge 自动事件验收，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3_Task_Report.md)。

### R3.1 [completed]

基于 PR #1925 合并后的真实自动事件继续修复 OTel 运行面：禁止 PaC Repository 参数未就绪时把花括号占位符作为 endpoint；从 owning YAML 在 source snapshot 内解析 OTel 配置并保留 300ms 非阻塞策略，增加安全的原始 fetch cause 投影；恢复 Tempo endpoint 后，用新的普通 PR merge 自动事件证明 collector 接收且 Tempo 可按 traceId 查询，禁止人工触发 PipelineRun，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.1_Task_Report.md)。

### R3.2 [completed]

基于真实自动事件 `hwlab-web-probe-sentinel-nc01-bbjv2` 修复 BuildKit daemon 已启动但 readiness 重试提前耗尽的竞争，并让 PaC `history/debug-step/status` 从失败 TaskRun 日志默认有界投影 traceId、首断点、阶段、error type/code/exit 与精确下钻；不得以人工 PipelineRun、锁/租约或吞掉失败缓解，使用下一次普通 PR merge 自动事件证明业务成功且 Tempo 可按同一 traceId 查询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.2_Task_Report.md)。

### R3.3 [completed]

基于真实自动事件 `hwlab-web-probe-sentinel-nc01-czhg5` 修复 `moby/buildkit:rootless` 启动合同：显式通过 RootlessKit 启动 buildkitd，保留 socket + worker readiness、有界 TERM/KILL/wait 与 typed 失败投影；禁止退回短连接重试、人工 PipelineRun 或第二 authority，使用下一次普通 PR merge 自动事件证明 image build、GitOps/Argo/runtime 成功且 Tempo 可按同一 traceId 查询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.3_Task_Report.md)。

### R3.4 [completed]

独立溯源 Web Probe Sentinel CI 从历史可成功构建到连续 BuildKit readiness 失败的首个回归：对齐成功/失败 PipelineRun、镜像 digest、TaskSpec、节点环境与 Git 提交/PR/作者，区分环境启动变慢、官方 daemonless 默认重试窗口不足和 PR #1939 裸 buildkitd 新回归，输出可复核的时间线与责任变更，不修改运行面或人工触发 PipelineRun，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R3.4_Task_Report.md)。

## R4 [in_progress]

解决 [AgentRun #352](https://github.com/pikasTech/agentrun/issues/352)、[HWLAB #2525](https://github.com/pikasTech/HWLAB/issues/2525) 与 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949)：消除 trace trc_f389d0493c0c489e 的 Kafka outbox 队头阻塞与 17 分钟伪耗时，恢复 agentrun.event.v1→transactional projector→hwlab.event.v1→实时/回放 SSE 单一权威；禁止 HTTP 补链、页面轮询、读侧修复、进程内 finalizer、双 authority、额外锁/租约/状态库或降低 Kafka/SSE 能力，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4_Task_Report.md)。

### R4.1 [in_progress]

执行 [AgentRun #352](https://github.com/pikasTech/agentrun/issues/352)：按 key 保序、跨 key 有界并行排空 transactional outbox，保留 durable at-least-once 并补 backlog/oldest/rate/typed error 可见性，以 NC01/nc01-v02 真实积压归零和新事件实时发布验收，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.1_Task_Report.md)。

### R4.2 [in_progress]

执行 [HWLAB #2525](https://github.com/pikasTech/HWLAB/issues/2525)：恢复固定 group transactional projector、原子 facts/checkpoint/browser outbox、hwlab.event.v1 relay 与同 cursor 实时/回放 SSE；耗时取 canonical 时间，禁止 direct/live 双写、HTTP 补链和页面轮询，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.2_Task_Report.md)。

### R4.3 [in_progress]

执行 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949)：由 config/hwlab-node-lanes.yaml 选择 transactionalProjector、projectionOutboxRelay、projectionRealtime 单一产品 authority，关闭 live-only direct authority，保持 renderer/status/preflight YAML-first，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.3_Task_Report.md)。

### R4.4

依赖 R4.1-R4.3，主代理完成 PR 架构审核、顺序合并、自动 CI/CD 和 NC01/v03 原 Workbench 新 hi turn 验收；核对 command/run 实际耗时、Kafka backlog/lag、运行中增量、terminal/final、刷新 replay、公开 result 与 OTel 一致后收口，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4_Task_Report.md)。