OpenTelemetry（OTel）

一句话定义

OpenTelemetry = 一套开放的可观测性标准与工具集，用统一的方式采集和传输日志、指标与追踪数据，使应用不绑定特定观测后端。

解决什么问题

没有 OTel 时，每个观测后端有自己的 SDK 和协议。更换后端意味着改代码。

无 OTel：
  App → SDK-A → 后端 A
  App → SDK-B → 后端 B     （换后端要改代码）

有 OTel：
  App → OTel SDK → OTel Collector → 任意后端
                                    ├── Loki
                                    ├── Elasticsearch
                                    └── 自建

三大信号

在 Agent Harness 中的体现

DeepSeek Harness 把遥测做成能力接缝，Provider 直接使用 OTel：

dsh-session-telemetry         ← Service Definition（ctx.sessionTelemetry）
    ↓
dsh-session-telemetry-otel    ← Service Provider，原样配置的 OTel JS SDK
    ↓
外部观测后端

设计要点：Harness 不自建观测后端，接入标准生态。

同时明确了一条边界：

边界公理（harness 的职责止于 emit()；批处理、重试、排队与丢失策略都属于上报 SDK）

即：**Harness 只负责产生遥测记录，传输可靠性交给 OTel SDK。**这避免了在 Harness 里重复实现队列、重试和降级逻辑。

Trace 与 Span

追踪的核心结构是 trace 与 span：

trace（一次完整请求）
├── span: prompt-assembly
├── span: llm-request
├── span: tool/call
│   └── span: approval-request
└── span: tool/result

每个 span 记录起止时间、属性和状态。通过 span 树能定位「这次任务 80% 的时间花在审批等待上」。

相关

• 第 17 讲 可观测性
• Capability Seam（能力接缝） — 遥测作为接缝，Provider 可替换
• LogQL — 查询日志的典型语言，常与 OTel 采集的数据配合