Files

T

Codex 4928cfc9b8 docs: 新增 UniDesk OTel skill

2026-06-20 01:29:35 +00:00

5.3 KiB

Raw Blame History

name, description

name	description
unidesk-otel	UniDesk OpenTelemetry/Tempo 链路追踪运维技能。用户提到 OTel、OpenTelemetry、Tempo、trace backend、platform-infra observability、链路追踪、按 traceId 查 span、provider-stream-disconnected、Code Agent/AgentRun/HWLAB 跨服务追踪、或要求“用 otel 查/改进 otel”时使用。

UniDesk OTel

Skill(cli-spec)

UniDesk 的 OTel 运行面在 platform-infra namespace：OTel Collector 负责接收 OTLP traces，Tempo 负责查询。操作入口统一走 UniDesk YAML-first CLI，不直接 kubectl port-forward、手写 Tempo API 或裸 curl。

固定入口: cd /root/unidesk && bun scripts/cli.ts platform-infra observability ...

基本状态

bun scripts/cli.ts platform-infra observability status --target D601
bun scripts/cli.ts platform-infra observability validate --target D601

status 检查 platform-infra namespace、otel-collector、tempo Deployment/Service/Pod 和 readiness probe。
validate 生成一条测试 trace，经 Collector 写入 Tempo，再通过受控 service proxy 查询，证明采集和查询闭环可用。
--full 只在需要展开远端 stdout/stderr 或完整 status payload 时使用；默认输出必须保持低噪声。

查询 Trace

bun scripts/cli.ts platform-infra observability trace \
  --target D601 \
  --trace-id <otelTraceId>

--trace-id 是 32 位 hex OpenTelemetry trace id，不是业务 traceId。默认输出只返回有界摘要：

spanCount、serviceCount、services
businessTraceIds
errorSpanCount
spanNameCounts
errorSpans
去重后的关键 spans
下一步 drill-down 命令

默认输出不得展开完整 Tempo JSON；需要原始响应时才用 --raw。

噪声压制

按错误文案、span 名、failureKind 或关键属性定位时，优先用 --grep：

bun scripts/cli.ts platform-infra observability trace \
  --target D601 \
  --trace-id <otelTraceId> \
  --grep provider-stream-disconnected \
  --limit 20

--grep <text> 在 span 名、status message 和关键 attributes 的摘要 JSON 中过滤。
--limit <N> 控制返回 span 数，避免大 trace 淹没上下文。
--full 展开完整 span 摘要，但仍不输出 Tempo raw body。
--raw 仅用于排查 Tempo 响应结构、CLI 解析器或后端返回本身。

业务 Trace 映射

HWLAB/Code Agent 的业务 traceId 通常形如 trc_...。当已知 OTel trace id 时，直接用 trace --trace-id 查询；当只知道业务 traceId 时，优先从 HWLAB trace/result、Code Agent result 或已记录的 issue 证据中取得对应 OTel trace id。不要为了找 OTel trace id 去打印 Secret、Authorization header、完整 DSN 或运行面 raw transcript。

OTel trace 内常见业务关联属性：

traceId: HWLAB 业务 traceId
otel.trace_id: OTel trace id
runId / commandId: AgentRun run/command
sessionId / turnId / threadId: HWLAB/AgentRun 会话与 turn 关联
failureKind / willRetry / terminalStatus: 错误与终态判断

Code Agent / AgentRun 排障

追 Code Agent 代理暂时无法连接上游、provider-stream-disconnected、Workbench 加载/转圈、turn idle 报错、AgentRun command terminal 状态时：

先确认 OTel backend ready： bun scripts/cli.ts platform-infra observability status --target D601
查业务 trace 对应 OTel trace： bun scripts/cli.ts platform-infra observability trace --target D601 --trace-id <otelTraceId>
用错误关键词过滤： bun scripts/cli.ts platform-infra observability trace --target D601 --trace-id <otelTraceId> --grep <failureKind-or-message> --limit 20
对照 errorSpanCount、matchedSpanCount、terminalStatus、willRetry、runId、commandId 判断是 terminal failure、retryable transient 还是旧 trace 缺 instrumentation。

旧 trace 不会因为后续 instrumentation 修复自动回填。若旧 trace 查不到错误 span，但新的 canary/真实 trace 能查到同类 runner_error.* span，应把旧 trace 结论写成“当时未采集到该事件”，不要倒推出运行面没有发生过错误。

何时先改进 OTel

遇到以下情况，先修 OTel CLI 或 instrumentation，再继续业务排障：

trace 命令只能返回 raw/tail，不能给出可读 span 摘要。
大 trace 输出淹没上下文，缺少 --grep、--limit、错误 span 汇总或下一步 drill-down。
关键 runner/backend/projection 事件只存在业务事件流，不进入 OTel。
error span 缺 failureKind、willRetry、terminalStatus、runId、commandId 等定位字段。
CLI 默认输出 Secret、Authorization header、DSN 或其他敏感值。

改进后必须用一条 canary 或真实 trace 证明新 span/摘要可查询，再继续定位原业务问题。

交付边界

OTel 平台配置真相是 config/platform-infra/observability.yaml。
OTel CLI 实现在 scripts/src/platform-infra-observability.ts，帮助入口由 scripts/src/platform-infra.ts 暴露。
修改 OTel CLI 属于 UniDesk 轻量 CLI 变更：默认只做语法检查、命令形态验证和真实 trace 查询，不新增合同测试。
修改 AgentRun/HWLAB instrumentation 属于对应仓库/运行面的代码变更，必须按目标 repo 的 source truth、PR/CD 和原入口验收规则执行。

5.3 KiB Raw Blame History Unescape Escape