第8章：Agent Observability —— OTel GenAI / LangSmith / Langfuse

Agent 给了一句”奇怪的回答”,你怎么定位是哪步出错?LLM 调用花了 30 秒,瓶颈在哪?上线后 token 成本翻倍,谁在背锅?这些问题都靠 Observability——但 LLM 的可观测和传统 Web 服务不一样,Span 层级、字段语义、cost 统计都需要新标准。本章讲透 OTel GenAI Semantic Conventions(2025 业界事实标准)、LangSmith/Langfuse 的产品特性、自建 OTel pipeline,以及关键指标和告警设计。

📑 目录

• 1. 为什么 LLM 需要专门的 observability
• 2. OpenTelemetry GenAI Semantic Conventions
• 3. Span 层级:Workflow → Agent → LLM → Tool
• 4. LangSmith — LangChain 一体化
• 5. Langfuse — 开源 + OTel 兼容
• 6. 横向对比与选型
• 7. 自建 OTel pipeline
• 8. 关键指标与告警
• 自我检验清单
• 参考资料

---

1. 为什么 LLM 需要专门的 observability

1.1 传统 APM 不够用

传统 APM(DataDog、New Relic):

• ✅ HTTP request / DB query / RPC trace
• ❌ LLM token usage 不知道
• ❌ Prompt / Completion 看不到内容
• ❌ Tool call 没有专门 span
• ❌ 多 agent handoff 没标准
• ❌ Cost 计算靠自己

1.2 LLM observability 的额外需求

需求	为什么
Token 计数	每个 LLM call 的输入/输出 token,直接 = 钱
完整 prompt/response	调试 LLM 行为必备
Provider / Model	一个 agent 可能用多个模型,要能区分
Tool call 嵌套	LLM 调 tool A,tool A 调 LLM 再调 tool B…
Memory read/write	模块五的所有 memory 操作都要可见
Cost 标注	每个 span 算成本,聚合到 user / session
错误重试	LLM API 抖动时的重试要可见

🌟 没有 LLM-aware observability,生产 agent 等于盲飞。

---

2. OpenTelemetry GenAI Semantic Conventions

2.1 起源

各家(LangFuse、LangSmith、Helicone、Traceloop、Portkey)早期各搞各的字段——gen_ai_model / model_name / model.id…,用户切平台必须重写 instrumentation。

OpenTelemetry GenAI SIG 从 2024-04 开始统一,2025-Q3 v1.37 正式入主 spec——业界事实标准。

2.2 关键属性(摘录)

属性	含义	例子
gen_ai.system	系统名	openai / anthropic / vllm
gen_ai.request.model	请求的 model	gpt-4o-2024-11-20
gen_ai.response.model	响应实际用的 model	gpt-4o-2024-11-20
gen_ai.usage.input_tokens	输入 token 数	1500
gen_ai.usage.output_tokens	输出 token 数	350
gen_ai.request.temperature	采样温度	0.7
gen_ai.request.max_tokens	最大输出	4096
gen_ai.operation.name	操作类型	chat / embeddings / completion
gen_ai.tool.name	工具名	get_weather
gen_ai.tool.call.id	工具调用 ID	call_abc123
gen_ai.agent.id	agent ID	sales_agent_v3
gen_ai.conversation.id	会话 ID	conv_xyz

2.3 Span Event(prompt / completion 内容)

prompt / completion 通常太大放在 attribute 里,放成 events:

Span: chat.completion
  events:
    - name: gen_ai.user.message
      attributes:
        content: "北京天气怎么样?"
    - name: gen_ai.assistant.message
      attributes:
        content: "北京今天 24°C 多云"
    - name: gen_ai.tool.message
      attributes:
        tool_name: get_weather
        content: '{"temp": 24}'

这样既可见又不爆 attribute size。

2.4 隐私开关

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false 关闭 prompt/completion 内容采集,保留 metadata——满足 GDPR / HIPAA 等场景。

---

3. Span 层级:Workflow → Agent → LLM → Tool

Trace: order_processing_request
│
└─ Span: workflow.order_processing  (Temporal workflow / LangGraph thread)
    │
    ├─ Span: agent.supervisor       (LangGraph supervisor node)
    │   │
    │   └─ Span: gen_ai.chat        (LLM call: 决定路由)
    │       attributes:
    │         gen_ai.system = openai
    │         gen_ai.request.model = gpt-4o
    │         gen_ai.usage.input_tokens = 800
    │         gen_ai.usage.output_tokens = 50
    │
    ├─ Span: agent.sales            (worker subgraph)
    │   │
    │   ├─ Span: memory.search      (Mem0 检索)
    │   ├─ Span: gen_ai.chat        (LLM 推理)
    │   └─ Span: tool.create_order  (MCP tool)
    │       │
    │       └─ Span: db.query       (内部数据库)
    │
    └─ Span: agent.notification     (worker subgraph)
        └─ Span: tool.send_email

每一层都是 Span,父子关系清晰——点开一条 trace 就能看到完整 agent 行为。

---

4. LangSmith — LangChain 一体化

4.1 哲学

“为 LangChain / LangGraph 量身定做,开箱即用。“

4.2 核心能力

能力	说明
自动 trace	LangGraph / LangChain 代码零侵入,自动把每步 trace 上报
Prompt playground	看到生产 prompt 直接调试
Dataset & Evals	把生产 trace 转成测试集,跑 evaluator
Production monitoring	实时仪表盘:latency、token、error rate
Annotation queue	人工标注 trace,反馈给 model fine-tune
OTel 双向兼容	既能接 OTel 数据进来,也能把 LangSmith trace 推到外部 OTel

4.3 接入

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "ls__..."
os.environ["LANGSMITH_PROJECT"] = "production-agent"

# 然后正常用 LangChain / LangGraph,自动上报
from langgraph.prebuilt import create_react_agent
agent = create_react_agent(...)
agent.invoke(...)  # 自动 trace 到 LangSmith

4.4 优劣

✅ 零摩擦(用 LangChain 栈的话) ✅ Eval / Dataset 工作流是一等公民 ✅ 企业级 SaaS + 自托管 enterprise edition

❌ 有 vendor lock-in 倾向(虽然有 OTel 桥接) ❌ 价格贵(按 trace 数收费)

---

5. Langfuse — 开源 + OTel 兼容

5.1 哲学

“开源、可自托管、原生 OTel 兼容。“

5.2 核心能力

能力	说明
Apache 2.0 开源	自托管完全免费
OTel 原生	接收 OTel GenAI 数据,无需改代码
多框架支持	LangChain / LlamaIndex / AutoGen / CrewAI / 直接 OpenAI SDK
Prompt 管理	版本化 prompt,A/B 测试
Dataset & Evals	同 LangSmith
Cost & Token analytics	按 user / project / model 维度

5.3 接入(OTel 模式)

# 任何 OTel-instrumented 应用都能接 Langfuse
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

OTLPSpanExporter(
    endpoint="https://cloud.langfuse.com/api/public/otel/v1/traces",
    headers={"Authorization": f"Basic {public_key}:{secret_key}"},
)

5.4 接入(SDK 模式)

from langfuse.openai import OpenAI   # 包装过的 client

client = OpenAI()
client.chat.completions.create(...)   # 自动上报

5.5 优劣

✅ 完全开源,自托管友好 ✅ 多框架,无 lock-in ✅ OTel 兼容 = 长期不会被淘汰

❌ UI 不如 LangSmith 精致 ❌ 企业级 features(SSO、audit log、custom RBAC)在 enterprise 版

---

6. 横向对比与选型

6.1 主流平台速查

平台	出品方	开源?	OTel	自托管	适合
LangSmith	LangChain	❌	✅	Enterprise only	LangChain 栈、需 evaluator workflow
Langfuse	Langfuse	✅ Apache 2.0	✅ 原生	✅ Self-host	开源派、多框架、合规
Helicone	Helicone	✅ MIT	✅	✅	简单 logging、proxy 模式
Phoenix(Arize)	Arize	✅ ELv2	✅	✅	强 RAG eval、evaluator 库
Traceloop OpenLLMetry	Traceloop	✅	✅	✅	OTel-only stack
Portkey	Portkey	❌	✅	Enterprise	LLM gateway + observability 一体
Logfire	Pydantic	部分开源	✅	✅	与 Pydantic AI 深度集成

6.2 选型决策树

你的栈?
│
├─ LangChain / LangGraph
│   └─ LangSmith(零摩擦) 或 Langfuse(开源)
│
├─ Pydantic AI
│   └─ Logfire
│
├─ 自定义 / 多框架混用
│   └─ Langfuse(OTel 兼容性最好)
│
├─ 强 RAG eval 需求
│   └─ Phoenix(Arize)
│
├─ 仅做 cost / latency proxy
│   └─ Helicone
│
└─ 企业级 LLM gateway + obs
    └─ Portkey

6.3 双栈策略也常见

很多团队同时用:

• Langfuse 做主 observability(开源、合规)
• LangSmith 做 LangChain 代码调试(开发体验最好)
• DataDog / New Relic 做基础设施(沿用现有 APM)

通过 OTel 一份数据 → 多家 backend。

---

7. 自建 OTel pipeline

7.1 最简栈

Application(LangGraph + OTel SDK)
       │
       ▼ OTLP(gRPC / HTTP)
┌──────────────────┐
│  OTel Collector  │  ← 收集、过滤、转换
└──────────────────┘
       │
       ├──► Tempo / Jaeger    (trace)
       ├──► Prometheus        (metric)
       ├──► Loki              (log)
       └──► Langfuse          (LLM-specific)
            ↓
       Grafana 统一可视化

7.2 给 LangGraph 加 OTel

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.langchain import LangChainInstrumentor

# 1. 配置 OTel SDK
provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://collector:4317"))
)
trace.set_tracer_provider(provider)

# 2. 自动 instrument LangChain / LangGraph
LangChainInstrumentor().instrument()

# 3. 现在所有 LangGraph 调用都自动 trace

openinference-instrumentation-* 系列(Arize 出品)覆盖 LangChain、LlamaIndex、OpenAI SDK、Anthropic SDK 等,零侵入。

7.3 自定义 span

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

def my_node(state):
    with tracer.start_as_current_span("agent.my_node") as span:
        span.set_attribute("gen_ai.agent.id", "sales_v3")
        span.set_attribute("user_id", state["user_id"])
        # ... do work ...
        span.set_attribute("result_count", len(results))
        return {"results": results}

---

8. 关键指标与告警

8.1 必采集的指标

指标	计算	告警阈值
Latency P50 / P95	end-to-end agent response 时间	P95 > SLO
TTFT(streaming)	首 token 到达时间	> 1s
Tokens per request	input + output	异常飙升
Cost per request	tokens × 单价	异常飙升
Cost per user-day	用户级聚合	高消耗用户 alarm
Tool error rate	failed tool / total tool	> 1%
LLM error rate	LLM 失败 / 总 call	> 0.5%
Saga compensation rate	compensate / total saga	> 5%(模块六第 6 章)
Agent loop length	平均 step 数	突然增长可能死循环
Memory hit rate	retrieval 非空 / 总查询	< 60%(模块五)
Provider mix	各 provider 调用比例	异常切换可能 quota 问题

8.2 业务相关指标

指标	例子
Goal completion rate	用户目标(下单 / 解决问题)完成率
Handoff rate	多 agent 系统中的转交频率
Human escalation rate	升级人工的比例
User satisfaction	thumbs up / down / 评分

8.3 告警与回归

# Prometheus alert
groups:
- name: agent_alerts
  rules:
  - alert: HighLatency
    expr: histogram_quantile(0.95, rate(agent_response_duration_seconds_bucket[5m])) > 5
    for: 5m
    annotations:
      summary: "Agent P95 latency > 5s"
  
  - alert: CostSpike
    expr: rate(gen_ai_cost_usd[1h]) > 1.5 * avg_over_time(rate(gen_ai_cost_usd[1h])[1d])
    for: 30m
    annotations:
      summary: "Hourly cost > 1.5x daily average"
  
  - alert: CompensationStorm
    expr: rate(saga_compensation_total[5m]) > 0.1
    annotations:
      summary: "Saga compensation rate > 10%, possible system issue"

8.4 性能回归 CI

每次提交跑一个标准 task 集,对比基准:

def perf_regression_test():
    score = run_eval_set("standard_tasks", agent_version="HEAD")
    baseline = read_baseline()
    
    if score.latency_p95 > baseline.latency_p95 * 1.1:
        fail("P95 latency 退化超过 10%")
    if score.cost_per_task > baseline.cost_per_task * 1.05:
        warn("Cost per task 退化超过 5%")

---

✅ 自我检验清单

• LLM observability vs 传统 APM:能列出至少 5 类 LLM 特有的需求
• OTel GenAI 关键属性:能默写 gen_ai.system / model / usage.input_tokens / operation.name 等
• Span Event 的用途:能解释为什么 prompt/completion 放 event 而非 attribute
• Span 层级:能画出 Workflow → Agent → LLM → Tool 的嵌套
• LangSmith vs Langfuse:能用 5 个维度对比
• OTel 自建 pipeline:能画出最简 collector → tempo + prometheus + grafana 架构
• OpenInference:能用 LangChainInstrumentor() 一行接入 LangGraph
• 必采指标:能列出至少 8 个核心指标和告警阈值
• 业务指标:能为某个业务设计 4 个业务级指标
• CI 回归:能写一段 perf_regression_test 脚本

---

📚 参考资料

标准

• OpenTelemetry GenAI Semantic Conventions:opentelemetry.io/docs/specs/semconv/gen-ai
• AI Agent Observability — OpenTelemetry Blog 2025:opentelemetry.io
• OpenTelemetry GenAI Semantic Conventions for LLM Observability:DEV

平台

• LangSmith:smith.langchain.com | 文档
• Langfuse:langfuse.com | GitHub | OTel 集成
• Phoenix(Arize):github.com/Arize-ai/phoenix
• Helicone:helicone.ai
• Traceloop OpenLLMetry:github.com/traceloop/openllmetry
• Portkey:portkey.ai | OTel 解读
• Logfire(Pydantic):pydantic.dev/logfire

工程实践

• OpenInference Instrumentations:github.com/Arize-ai/openinference
• AI Agent Observability in 2026: OpenAI Agents SDK, LangSmith, OpenTelemetry:DEV
• Agent Observability: Can the Old Playbook Handle the New Game?:Greptime
• OpenTelemetry just standardized LLM tracing:DEV