---
name: unidesk-otel
description: 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 OpenTelemetry/Tempo 链路追踪运维、按 traceId 查 span、Code Agent/AgentRun/HWLAB 跨服务追踪，以及 provider-stream-disconnected 等问题定位。

## 高频入口

```bash
bun scripts/cli.ts platform-infra observability status
bun scripts/cli.ts platform-infra observability closeout --target <NODE> [--query <PromQL>]... [--trace-id <traceId>] [--service <service>]
bun scripts/cli.ts platform-infra observability trace <traceId>
bun scripts/cli.ts platform-infra observability search --grep <service> --limit 20
```

基本状态、trace 查询、噪声压制、读取窗口与乱序调查见 [references/traces.md](references/traces.md)；业务 trace 映射、Code Agent/AgentRun 排障、codex-stdio 追穿和何时先改进 OTel 见 [references/code-agent.md](references/code-agent.md)。

同类运行面复核优先用 `closeout` 一次汇总 status、validate 及显式选择的 PromQL/trace；子检查失败固定为 non-blocking warning，单项细节再走原命令下钻。

## P0 边界

- 微服务契约版本、源码/镜像版本和 `commitId` 漂移只能记录为非阻塞 warning；不得建议或实现线上 admission、dispatch、readiness 或用户业务门禁。业务已成功时，漂移告警不能改写成功结论。
- `diagnose-code-agent` 同时展示 AgentRun durable authority 与 HWLAB projection/read model：
  - 权威终态决定 `effectiveStatus`；
  - 投影滞后或冲突固定输出 `warning=true`、`blocking=false`；
  - `mutation=false` 表示该聚合入口只读，不执行补链或运行面修补。
- 可见性问题优先修复；状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出。
- 离线调查中的 OTel 只能分析既有 trace 和已有业务记录；如果 trace/search/diagnose 摘要不好用、缺少业务映射或无法区分 observability gap 与业务失败，先改进 OTel CLI/analyze/instrumentation 可见性，再继续业务结论。
- OTel 查询默认低噪声摘要；完整 span/context 显式 `--full`/`--raw`。
- OTel 查询的 `--target` 必须匹配 trace 所属运行面 node/lane；JD01 运行面产生的 trace 用 `--target JD01` 查询，不能拿其他节点查询失败当作 trace 缺失结论。
- 不把 trace 缺口误判成业务成功；缺少 span 或窗口不完整时，先说明观测边界。
- `diagnose-code-agent` 的 `observabilityGap` / `Service trace coverage` 是跨服务追穿完整性证据：如果 business trace 只有 `hwlab-cloud-api`，但缺少 `agentrun-manager` 或 `agentrun-runner`，应按观测缺口记录并继续用 runId/commandId/sessionId drill-down，不要把缺失 span 当作服务未参与的业务结论。
- `platform-infra observability status` 默认应保持短表；需要完整 Kubernetes/Tempo payload 时才显式使用 `--full` 或 `--raw`。

## 何时读取 reference

- 查具体 traceId、span、服务过滤或噪声压制时，读 [references/traces.md](references/traces.md)。
- 排障 Code Agent/AgentRun/HWLAB 链路时，读 [references/code-agent.md](references/code-agent.md)。
- 判断是否需要先改进 OTel 或交付边界时，读 [references/code-agent.md](references/code-agent.md)。
