pikasTech-unidesk/.agents/skills/unidesk-otel/SKILL.md

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

高频入口

bun scripts/cli.ts platform-infra observability status
bun scripts/cli.ts platform-infra observability trace <traceId>
bun scripts/cli.ts platform-infra observability search --service <service> --limit 20

基本状态、trace 查询、噪声压制、业务 trace 映射、Code Agent/AgentRun 排障、codex-stdio 追穿、读取窗口与乱序调查、何时先改进 OTel 的细节见 references/full.md。

P0 边界

• 可见性问题优先修复；状态、耗时、失败原因、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/full.md 的查询和噪声段。
• 排障 Code Agent/AgentRun/HWLAB 链路时，读业务映射和 Code Agent/AgentRun 段。
• 判断是否需要先改进 OTel 或交付边界时，读对应段。