Codex
35 lines
2.7 KiB
Markdown
35 lines
2.7 KiB
Markdown
---
|
||
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 trace <traceId>
|
||
bun scripts/cli.ts platform-infra observability search --service <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)。
|
||
|
||
## 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/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)。
|