OBSERVABILITY
可观测性与链路追踪
按 Trace、Thread、Agent、组件和状态定位跨层事件，并保留降级与截断语义。
先说结论
“链路追踪”页面用于把一次跨前端、RPC、Thread、Turn、Agent 与 Tool 的失败收敛到同一 Trace。它查询最近事件与完整 Trace，并同时显示前端健康状态；用途是定位失败所有权，而不是用日志数量代替行为验证。
怎么理解
最近事件查询支持以下过滤器：Trace ID、Thread ID、Agent ID、组件、状态、Method、关键词与 Limit。状态包括 ok、slow、error、panic、sampled 和 dropped_summary。
页面先按 Trace ID 聚合匹配 event，再选择最有诊断价值的代表事件。组状态按严重度提升：panic 高于 error，error 高于 slow。展开 Trace 后，默认只显示错误、panic、slow、有 error 字段的事件以及最后一个有意义的上下文事件；成功噪声可以按需展开。
| 结果字段 | 含义 |
|---|---|
source | 事件来自 memory 或 tail 等来源 |
truncated | 结果是否受 limit 截断 |
degraded | 查询是否在降级条件下返回 |
parse_error / tail_error | 日志解析或 tail 读取问题 |
tail_timed_out | tail 查询是否超时 |
total_duration_ms | Trace 返回的总耗时 |
怎么使用
- 从失败 UI、Thread、Turn 或 Tool 事件中取得 Trace ID；没有 Trace ID 时先用 Method、组件、状态或关键词查询最近日志。
- 设置正整数 Limit，选择
error、panic或slow优先缩小范围，然后点击“查询最新日志”。 - 查看匹配 event 分组的时间、最坏状态、摘要、耗时、Thread 和错误信息，同时确认 source、truncated 与 tail diagnostics。
- 复制 Trace ID 作为排障关联键，选择“打开 Trace”读取完整事件序列。
- 先看默认关键事件；需要确认前后顺序或正常路径时再选择“显示全部事件”。
- 对每个事件核对请求上下文、trace/span/parent、thread/turn/agent/call/tool 标识、代码位置、失败原因、调用栈和附加信息。
- 结合页面下方 Frontend Health 判断问题是数据查询、前端投影还是业务执行失败，再重复原始操作验证恢复。
常见问题
- 查询没有结果：放宽 status、component 或 keyword，增大 Limit，并确认 ID 没有多余空白。
- Limit 非正整数：修正输入；服务层会拒绝零、负数、小数和非数字字符串。
truncated=true：缩小过滤条件或提高 Limit，不能把当前列表解释为完整 Trace 集合。degraded=true、parse_error、tail_error或tail_timed_out=true：保留诊断字段，区分“没有事件”和“事件来源不完整”。- Trace 加载失败或响应缺少 events 数组：按数据契约错误处理并查看 Health；页面不会伪造空事件数组掩盖 malformed response。
- 复制 Trace ID 失败：手工记录页面值，同时保留复制动作错误；不要因此丢弃原 Trace。
适用范围
- Trace 是诊断证据，不自动证明业务正确、安全或变更已经交付。
sampled与dropped_summary表示可观测性策略状态，不等价于业务错误。- 默认关键事件视图会折叠成功过程事件；完整时序需要主动显示全部。
- 查询结果可能来自内存与日志 tail 的组合，应连同 source 和降级字段一起解释。
- 公开支持请求必须脱敏 Trace、路径、用户数据、Provider 内容与凭据。