阶段 6：实战集成案例

预计学习时间：1-2 天
本章结合本仓库真实代码，讲解两种典型接入模式。

---

目录

1. 三种接入模式总览
2. 案例 A：Claude Code → Langfuse
3. 案例 B：tRPC-Agent → Langfuse
4. 概念映射：Claude Code 视角
5. 方案选型指南
6. 学习检查

---

1. 三种接入模式总览

模式 1: SDK 直写          你的代码 ──→ Langfuse SDK ──→ Server
模式 2: OTel 桥接         框架 OTel ──→ OTLP Exporter ──→ Langfuse
模式 3: 旁路解析          外部日志文件 ──→ 解析器 ──→ Langfuse SDK

模式	侵入性	典型场景
SDK 直写	中（需埋点）	自研 Chatbot、脚本
OTel 桥接	低（框架已埋点）	tRPC-Agent、LangChain
旁路解析	零（不改主程序）	Claude Code、第三方 CLI

---

2. 案例 A：Claude Code → Langfuse

2.1 背景

Claude Code 把每次会话写入本地 jsonl transcript，格式类似：

{"type":"user","message":{"role":"user","content":"帮我写个函数"},"timestamp":"..."}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"好的..."}]},"timestamp":"..."}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{...}}]},"timestamp":"..."}

官方没有直接集成 Langfuse，但 transcript 里已经包含完整对话和工具调用——可以旁路解析上报。

详细设计文档：../../ai/cli/claudecode/langfuse_trace/方案实现说明.md

2.2 数据流

Claude Code 写 jsonl
        │
        ▼
┌───────────────────┐
│ 解析 transcript    │
│ - 按 Turn 切分     │
│ - 识别 tool_use    │
│ - 匹配 subagent    │
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ Langfuse SDK v2   │
│ trace()           │
│ ├── generation()  │
│ └── span(tool)    │
└─────────┬─────────┘
          ▼
    Langfuse Server

2.3 两种上报方案

维度	Hook（方案 A）	Watcher（方案 B）
触发	Claude Code Stop 事件	独立进程轮询 jsonl
实时性	每轮结束上报	默认 1s 轮询
配置	改 settings.json hooks	后台运行脚本
适用	深度集成	CI / 不便改 Hook

⚠️ 二者勿同时启用，否则同一 Turn 会重复上报。

2.4 Langfuse 概念映射

Claude Code 概念          Langfuse 概念
─────────────────────────────────────────
一轮用户问答（Turn）   →   Trace
模型回复（assistant）  →   Generation
工具调用（tool_use）   →   Span (tool)
子代理（Task/Agent）   →   嵌套在 Tool: Agent 下的子 Trace
整个 coding session    →   Session（可选）

2.5 快速开始

cd ../../ai/cli/claudecode/langfuse_trace
pip install -r requirements.txt

export TRACE_TO_LANGFUSE=true
export CC_LANGFUSE_PUBLIC_KEY=pk-lf-xxx
export CC_LANGFUSE_SECRET_KEY=sk-lf-xxx

• Hook 方案：见 hook/README.md
• Watcher 方案：见 watcher/README.md

2.6 关键设计亮点

1. 真实时间戳：从 jsonl 的 timestamp 字段提取，UI 不再显示 0.00s
2. Token 统计：message.usage → usage_details，支持成本分析
3. 子代理嵌套：Task/Agent 工具调用会匹配 subagents/agent-*.jsonl，把子代理内部调用嵌套上报
4. fail-open：任何异常都 return 0，绝不影响 Claude Code 正常运行
5. 可靠投递：flush() 成功后才推进 offset，失败会重试

2.7 生活类比

Claude Code 像厨师在厨房记了手写流水账（jsonl）；Hook/Watcher 像「会计」定期把流水账录入 ERP（Langfuse），厨师不用改变做菜方式。

---

3. 案例 B：tRPC-Agent → Langfuse

3.1 背景

tRPC-Agent（腾讯开源 Agent 框架）内置 OpenTelemetry 埋点。Langfuse 集成通过 OTel 桥接 实现，而非直接调用 Langfuse SDK。

核心代码位于：

trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py

3.2 架构

tRPC-Agent 业务代码
        │
        ▼
tRPC-Agent 内置 OTel Tracer
（自动为 runner / agent / tool / LLM 创建 Span）
        │
        ▼
_LangfuseSpanExporter（自定义 Exporter）
  - 过滤无关 Span（HTTP 自动埋点等）
  - 映射 TRPC attribute → Langfuse attribute
        │
        ▼
OTLP HTTP → Langfuse Server

3.3 核心类

@dataclass
class LangfuseConfig:
    public_key: Optional[str] = None
    secret_key: Optional[str] = None
    host: Optional[str] = None
    batch_export: bool = True
    compatibility_old_version: bool = False
    enable_a2a_trace: bool = False

3.4 Span 过滤逻辑

不是所有 OTel Span 都上报 Langfuse。_LangfuseMixin._should_skip_span() 会过滤：

• a2a-python-sdk 的 Span
• OpenTelemetry 自动埋点的 HTTP/FastAPI Span
• 以 HTTP GET 等开头的 Span 名

为什么？ 就像餐厅监控只关心「做菜过程」，不需要录「快递员路过门口」。

3.5 Attribute 映射

tRPC-Agent 用 gen_ai.operation.name 区分操作类型：

operation.name	映射为 Langfuse
run_runner	Trace 级别
run_agent	Agent Observation
execute_tool	Tool Observation
chat / text_completion	Generation

映射函数 _map_attributes_to_langfuse() 把 tRPC 专有字段（如 trpc.agent.runner.name）转成 Langfuse 认识的 langfuse.trace.name、langfuse.observation.* 等。

3.6 启用方式

pip install trpc-agent-py[langfuse]

在 tRPC-Agent 配置中设置 Langfuse 公钥/私钥/host，框架启动时调用 langfuse_opentelemetry_setup(config) 注册 Exporter。

3.7 生活类比

tRPC-Agent 像连锁餐厅的中央厨房标准流程（OTel 埋点）；Langfuse 集成模块像「适配器」，把中央厨房的标准单据翻译成 Langfuse ERP 能识别的格式。

---

4. 概念映射：Claude Code 视角

用一次真实的编程对话理解层级：

Session: claude-code-session-abc
│
└── Trace: Turn 1 "帮我写个快排"
    ├── Generation: Claude 回复文本
    ├── Span (tool): Bash - 创建文件
    ├── Span (tool): Agent - 启动子代理
    │   └── [嵌套] Subagent Turn
    │       ├── Generation: 子代理回复
    │       └── Span (tool): Read - 读文件
    └── Generation: Claude 最终总结

在 Langfuse UI 里，你能展开看到这棵树，点击每个 Tool 查看 input/output。

---

5. 方案选型指南

你要追踪什么？
│
├── 自己写的 Python LLM 应用
│   └── 推荐：Langfuse SDK 直写（见 4_sdk_quickstart.md）
│
├── 基于 tRPC-Agent / LangChain 等框架
│   └── 推荐：框架自带 Langfuse / OTel 集成
│
├── Claude Code / Cursor 等 AI IDE
│   └── 推荐：旁路 jsonl 解析（本仓库 langfuse_trace）
│
└── 公司统一 OTel 基础设施
    └── 推荐：OTel Collector 多路导出到 Langfuse

决策矩阵

因素	SDK 直写	OTel 桥接	旁路解析
代码侵入	中	低	无
LLM 字段完整度	高	中-高	高（取决于解析器）
框架耦合	Langfuse	框架无关	文件格式耦合
维护成本	低	中	中-高

---

6. 学习检查

• [ ] 能说出 Claude Code 方案中 Hook 和 Watcher 的区别
• [ ] 能解释「一轮 Turn = 一条 Trace」的映射
• [ ] 理解 tRPC-Agent 为什么走 OTel 而不是 SDK 直写
• [ ] 知道 _should_skip_span 过滤 HTTP Span 的原因
• [ ] 能根据场景选择合适的接入模式

下一章 → 7_best_practices.md