04｜什么是OpenTelemetry：从统一规范到API与SDK

OpenTelemetry，简称 OTel，是一套厂商中立的可观测性框架。它统一了应用如何产生、描述、关联和导出 Trace、Metric、Log 等遥测数据。

OTel 不是一个监控后台，也不是存储数据库。它通常不负责长期保存数据和展示仪表盘，而是解决应用到观测后端之间的标准化问题。

OTel包含什么

组成	作用
Specification	定义跨语言的行为和数据要求
API	让代码创建 Span、Metric 和上下文
SDK	采样、处理、聚合和导出数据
Semantic Conventions	统一字段名称、类型和含义
OTLP	统一遥测数据的传输协议
Collector	接收、处理并路由遥测数据
Instrumentation	为框架和组件提供自动或手工埋点

这些部分共同形成一条厂商中立的数据链路。应用可以使用同一套 OTel 埋点，再把数据发送到不同的开源或商业后端。

API表达，SDK执行

OTel 将 API 与 SDK 分开。业务代码通过 Tracer、Meter 等 API 创建 Span 或指标；SDK 在运行时决定如何采样、处理和导出。这样，业务库只依赖稳定 API，不需要绑定某个具体后端。

业务代码 → OTel API → OTel SDK → Processor → Exporter

自动埋点适合 HTTP、数据库和常见框架；手工埋点适合任务规划、工具选择、Memory 检索等业务语义。两者结合，才能同时看到技术调用和 Agent 行为。

一个简单案例

报告 Agent 调用搜索工具后生成摘要。HTTP 自动埋点能够看到一次网络请求，却不知道这次调用属于“资料检索”。手工创建 retrieval Span，并添加任务类型、工具名称和结果数量后，查询才具有业务意义。

现实挑战：埋点改变了系统行为

如果每次模型流式输出都生成大量事件，或者同步导出所有 Span，遥测本身可能增加延迟。Agent 原本偶发超时，接入埋点后变得更加严重，团队容易误以为业务代码退化。

现象—假设—证据—判断

现象：启用 OTel 后 P95 延迟增加 800 毫秒。假设包括模型变慢、Exporter 阻塞、事件数量过多。证据显示模型耗时未变，关闭同步 Exporter 后延迟恢复，队列持续积压。判断：SDK 配置不当，遥测导出阻塞了请求线程。

改进措施包括批处理、异步导出、限制事件大小，并观察 SDK 自身的丢弃和队列指标。

Harness也需要手工语义

仅靠自动埋点看不到规划循环、重试原因和终止条件。Harness 应显式记录步骤类型、父步骤、循环次数、状态转换和失败分类。否则 Trace 很完整，却只能显示一串 HTTP 调用。

小结

OTel 是连接应用和观测后端的标准化框架，不是观测后端本身。API 让代码表达“这里发生了什么”，SDK 决定“数据怎样被处理”。自动埋点提供基础覆盖，手工埋点补充 Agent 业务语义。

延伸阅读：OpenTelemetry官方规范