[!info] related notes

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

OpenTelemetry

一句话定义

OpenTelemetry (OTel) 是可观测性的开源标准框架。它定义了 Traces（追踪）、Metrics（指标）、Logs（日志）三大信号的采集规范，让你可以用一套标准对接不同的后端（Jaeger、Prometheus、Grafana）。

核心原理

三大信号

信号	用途	例子
Traces	请求链路追踪	一次 Agent Run 的完整执行路径
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: "User X triggered tool Y with args Z"

Python 集成

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

# 初始化
provider = TracerProvider()
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("ai-service")

# 创建 Span
async def agent_run(context):
    with tracer.start_as_current_span("agent_run") as span:
        span.set_attribute("user_id", context.user_id)
        span.set_attribute("session_id", context.session_id)

        # LLM 调用 Span
        with tracer.start_as_current_span("llm_call") as llm_span:
            response = await llm.chat(messages)
            llm_span.set_attribute("model", response.model)
            llm_span.set_attribute("input_tokens", response.usage.input_tokens)

        # 工具调用 Span
        with tracer.start_as_current_span("tool_call") as tool_span:
            result = await execute_tool(tool_call)
            tool_span.set_attribute("tool_name", tool_call.name)

常见坑

1. 不做采样: 生产环境全量采集影响性能
2. 不传播 Context: 跨服务时 Trace 断裂
3. Span 太多: 每个 token 都创建 Span，数据量爆炸

参考资料

• OpenTelemetry
• Trace
• AI Service Observability