docs: 新增 UniDesk OTel skill
This commit is contained in:
Codex
@@ -0,0 +1,105 @@
|
||||
---
|
||||
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 的 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 ...`
|
||||
|
||||
## 基本状态
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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`：
|
||||
|
||||
```bash
|
||||
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 状态时：
|
||||
|
||||
1. 先确认 OTel backend ready：
|
||||
`bun scripts/cli.ts platform-infra observability status --target D601`
|
||||
2. 查业务 trace 对应 OTel trace：
|
||||
`bun scripts/cli.ts platform-infra observability trace --target D601 --trace-id <otelTraceId>`
|
||||
3. 用错误关键词过滤：
|
||||
`bun scripts/cli.ts platform-infra observability trace --target D601 --trace-id <otelTraceId> --grep <failureKind-or-message> --limit 20`
|
||||
4. 对照 `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 和原入口验收规则执行。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "UniDesk OTel"
|
||||
short_description: "UniDesk OpenTelemetry/Tempo tracing operations"
|
||||
default_prompt: "Use UniDesk OTel to inspect trace backend readiness and query Tempo traces with bounded summaries."
|
||||
Reference in New Issue
Block a user