主题
Langfuse 学习计划（从 0 到 1）
适合人群：刚接触 LLM 应用开发、想搞懂「模型到底干了什么」的小白
前置知识：了解什么是 API 调用即可，不要求会 OpenTelemetry
配套资料：同目录下的../opentelemetry/系列（学完 Langfuse 基础后建议继续）
一、学习目标
学完本系列，你应该能回答这些问题：
- Langfuse 是什么？和「打日志」有什么区别？
- Trace、Observation、Session、Generation 分别是什么？
- Langfuse 和 OpenTelemetry 是什么关系？能一起用吗？
- 怎么在自己的 Python 项目里接入 Langfuse？
- Claude Code / tRPC-Agent 是怎么把 trace 上报到 Langfuse 的？
二、学习路线总览
阶段 1: Langfuse 是什么 (半天)
阶段 2: 核心概念 (1 天)
阶段 3: 与 OpenTelemetry 关系 (半天)
阶段 4: SDK 快速上手 (1-2 天)
阶段 5: 平台能力 (1 天)
阶段 6: 实战集成案例 (1-2 天)
阶段 7: 生产最佳实践 (1 天)预计总时长：5-7 天（每天 1-2 小时）
三、详细学习计划
阶段 1：Langfuse 是什么（半天）
- 用生活例子理解「LLM 应用可观测性」
- Langfuse 解决什么问题
- 和 Jaeger / Grafana / 普通日志的对比
- 自托管 vs 云服务
小练习：在 langfuse.com 注册账号，浏览 Demo 项目里的 Trace 列表。
阶段 2：核心概念（1 天）
📄 阅读：2_core_concepts.md
- Trace（一次完整请求）
- Observation（请求里的每一步）
- Session（多轮对话的「聊天室」）
- Generation / Tool / Retriever 等 Observation 类型
- 属性传播：user_id、tags、metadata
生活类比主线：把 Langfuse 想象成一家餐厅的「后厨监控 + 顾客反馈系统」。
小练习：在 Langfuse UI 里点开一条 Trace，手动标出：根节点、Generation、Tool 调用。
阶段 3：与 OpenTelemetry 的关系（半天）
📄 阅读：3_langfuse_and_opentelemetry.md
- OpenTelemetry 是「通用快递标准」，Langfuse 是「专门收 AI 包裹的仓库」
- OTel Span ↔ Langfuse Observation 的映射
- 什么时候用 Langfuse SDK，什么时候走 OTel Exporter
- 和
../opentelemetry/学习路径的衔接
前置建议：若完全不懂 Trace/Span，先读 ../opentelemetry/1_base_concept.md 的前两节。
阶段 4：SDK 快速上手（1-2 天）
📄 阅读：4_sdk_quickstart.md
💻 代码：examples/basic_trace.py、examples/rag_agent_trace.py
- 安装与环境变量
- v2 有状态 API vs v3/v4 OTel API（本笔记以 v2 为主，更易上手）
trace()→generation()→span()的嵌套写法@observe装饰器- flush 与异步上报
小练习：跑通 basic_trace.py，在 Langfuse UI 看到一条完整 Trace。
阶段 5：平台能力（1 天）
- Prompt 管理（版本、A/B）
- Evaluation / Scoring（人工打分、LLM-as-Judge）
- Datasets 与实验
- Dashboard 与成本分析
阶段 6：实战集成案例（1-2 天）
- 案例 A：Claude Code transcript → Langfuse（Hook / Watcher）
- 案例 B：tRPC-Agent 框架通过 OpenTelemetry 接入 Langfuse
- 选型：SDK 直写 vs OTel 桥接 vs 旁路解析
阶段 7：生产最佳实践（1 天）
📄 阅读：7_best_practices.md
- 敏感信息脱敏
- 采样与成本控制
- fail-open 设计
- 自托管部署要点
四、文档目录结构
langfuse/
├── 0_learn_plan.md ← 本文件（学习地图）
├── 1_what_is_langfuse.md ← Langfuse 是什么
├── 2_core_concepts.md ← 核心概念（Trace/Observation/Session）
├── 3_langfuse_and_opentelemetry.md ← 与 OTel 的关系
├── 4_sdk_quickstart.md ← Python SDK 上手
├── 5_platform_features.md ← 平台能力（Prompt/Eval/Dashboard）
├── 6_integration_cases.md ← Claude Code / tRPC-Agent 集成
├── 7_best_practices.md ← 生产实践
└── examples/
├── basic_trace.py ← 最小可运行示例
└── rag_agent_trace.py ← RAG Agent 追踪示例五、与 a_why.md 问题对照
| 你的问题 | 对应章节 |
|---|---|
| Langfuse 的常见概念？ | 2_core_concepts.md |
| Langfuse 与 OpenTelemetry 的关系？ | 3_langfuse_and_opentelemetry.md |
| tRPC-Agent 如何集成 Langfuse？ | 6_integration_cases.md § tRPC-Agent |
| Claude Code 如何上报 trace？ | 6_integration_cases.md § Claude Code |
六、推荐学习资源
| 资源 | 链接 | 说明 |
|---|---|---|
| 官方文档 | https://langfuse.com/docs | 权威参考 |
| 数据模型 | https://langfuse.com/docs/observability/data-model | Trace/Observation 定义 |
| Python SDK | https://langfuse.com/docs/sdk/python | API 参考 |
| GitHub | https://github.com/langfuse/langfuse | 开源仓库 |
| 本地 OTel 笔记 | ../opentelemetry/ | 通用追踪基础 |
七、学习检查清单
阶段 1 ✅
- [ ] 能用一句话向同事解释 Langfuse 是干什么的
- [ ] 能说出它和「只打日志」的三个区别
阶段 2 ✅
- [ ] 能区分 Trace、Observation、Session
- [ ] 能说出 Generation 和 Span 的区别
- [ ] 能在 UI 里找到 token 用量和耗时
阶段 3 ✅
- [ ] 能解释 OTel Span 和 Langfuse Observation 的对应关系
- [ ] 知道 Langfuse 底层兼容 OTel 协议
阶段 4 ✅
- [ ] 成功运行 examples 并在 UI 看到数据
- [ ] 能手写一个三层嵌套 Trace（trace → generation → span）
阶段 5 ✅
- [ ] 了解 Prompt 版本管理的基本流程
- [ ] 知道如何给 Trace 打 Score
阶段 6 ✅
- [ ] 理解 Claude Code Hook 与 Watcher 两种方案
- [ ] 理解 tRPC-Agent 的 OTel → Langfuse 桥接思路
阶段 7 ✅
- [ ] 知道哪些数据不该上报（密钥、PII）
- [ ] 理解 fail-open：追踪挂了不能拖垮业务