From 7696fddccff290b1fe51e206c2de62f142c2908b Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 20 Jun 2026 03:55:47 +0000 Subject: [PATCH] docs: document otel trace window drilldown --- .agents/skills/unidesk-otel/SKILL.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.agents/skills/unidesk-otel/SKILL.md b/.agents/skills/unidesk-otel/SKILL.md index b80df0cc..e9150d76 100644 --- a/.agents/skills/unidesk-otel/SKILL.md +++ b/.agents/skills/unidesk-otel/SKILL.md @@ -98,6 +98,23 @@ OTel trace 内常见业务关联属性： 旧 trace 不会因为后续 instrumentation 修复自动回填。若旧 trace 查不到错误 span，但新的 canary/真实 trace 能查到同类 `runner_error.*` span，应把旧 trace 结论写成“当时未采集到该事件”，不要倒推出运行面没有发生过错误。 +## Trace 读取窗口与乱序调查 + +排查 HWLAB/Workbench trace 乱序、分页缺口、`--after-seq`/`--tail` 不生效、旧 trace 只返回局部事件或 read model 是否完整时，优先查 `trace_events_read` span： + +```bash +bun scripts/cli.ts platform-infra observability trace \ + --target D601 \ + --trace-id \ + --grep trace_events_read \ + --limit 20 \ + --full +``` + +摘要里重点看 `returnedEvents`、`sinceSeq`、`limit`、`fromSeq`、`toSeq`、`totalEvents`、`hasMore`、`fullTraceLoaded`、`rawEventCount`、`maxSeq`、`traceLastSeq`、`endSeq` 和 `commandFiltered`。这些字段用于判断“查询窗口是否正确传到后端”“后端是否只返回了局部事件”“read model 是否已经加载完整 trace”。若 `errorSpanCount=0` 但用户可见 timeline 仍乱序，先把结论写成展示/投影/renderer 调查 issue，不要把它定性为后端错误 span。 + +旧业务 trace 在 runtime 重启或保留策略后可能只剩局部事件；OTel 只能证明读取窗口、span 和当时观测到的字段，不能自动恢复业务事件流。需要验证新 instrumentation 时，使用新 canary 或仍可完整读取的真实 trace。 + ## 何时先改进 OTel 遇到以下情况，先修 OTel CLI 或 instrumentation，再继续业务排障：