[!info] related notes

• 所属 MOC: Observability Engineering MOC
• 相关: Trace, AI 服务可观测性

OpenTelemetry

一句话定义

OpenTelemetry (OTel) 是可观测性的开源标准框架。它定义了 Traces（追踪）、Metrics（指标）、Logs（日志）三大信号的采集规范，通过相应 exporter 对接后端；OTel 本身不提供统一的遥测存储和查询 UI，Collector 也不是长期存储。

核心原理

三大信号

信号	用途	例子
Traces	请求链路追踪	已埋点并被保留的 Agent 调用片段
Metrics	聚合指标	平均延迟、token 消耗、错误率
Logs	离散事件	”Tool X 调用失败”

在 AI Agent 中的应用

Traces: Agent Run → LLM Call → Tool Execution → LLM Call
Metrics: token_usage_total, llm_latency_seconds, tool_call_total
Logs: "tool_call completed status=ok"（按需脱敏）

Python 最小本地追踪

依赖 opentelemetry-sdk（项目中应锁定版本）。下面只生成演示 span 并输出到控制台，不调用真实模型或外部遥测服务：

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
tracer = provider.get_tracer("ai-service-demo")

try:
    with tracer.start_as_current_span("agent_run"):
        with tracer.start_as_current_span("llm_call") as span:
            span.set_attribute("demo.model", "simulated-model")
        with tracer.start_as_current_span("tool_call") as span:
            span.set_attribute("demo.tool_name", "search_knowledge")
finally:
    provider.shutdown()

应看到三个 span：两个调用 span 共享根 span 的 trace ID，并各自指向根的 span ID；它们不是彼此的父子。demo.* 是本例自定义属性，不冒充 OTel GenAI 语义约定。

单独创建 TracerProvider 不会把 span 送到后端，还需 processor/exporter；仅使用 API 且没有实际 SDK provider 时通常不会记录数据。生产环境一般用批处理导出并协调 flush/shutdown。HTTP context 传播与遥测导出是不同路径，见 多服务分布式追踪设计。

常见坑

1. 采样与完整性混淆：全量采集有成本，采样又可能丢失诊断片段；按负载配置，不假定 trace 永远完整。
2. 不传播 Context: 跨服务时 Trace 断裂
3. Span 太多: 每个 token 都创建 Span，数据量爆炸

参考资料

• OpenTelemetry
• Trace
• AI 服务可观测性设计