learnNote

主题

阶段 7：生产最佳实践 ​

预计学习时间：1 天

目录 ​

  1. 安全与隐私
  2. 性能与成本
  3. 可靠性设计
  4. 自托管要点
  5. 运维检查清单
  6. 学习检查

1. 安全与隐私 ​

1.1 什么不该上报 ​

数据类型风险建议
API Key / Secret泄露凭证脱敏或不上报
用户密码合规风险绝不上报
身份证号、银行卡PII 违规脱敏
完整用户聊天记录隐私按合规要求截断

1.2 脱敏策略 ​

本仓库 Claude Code 方案内置正则脱敏（可通过 CC_LANGFUSE_REDACT=false 关闭）：

  • Bearer Token
  • sk- / pk- 开头的密钥
  • password 字段
python
# 自己的代码里也可以手动截断
MAX_CHARS = 20000
safe_input = raw_input[:MAX_CHARS] + ("...[truncated]" if len(raw_input) > MAX_CHARS else "")

1.3 生活类比 ​

餐厅监控可以录后厨操作，但不能录顾客银行卡密码。可观测性也一样——录「过程」不录「密钥」。

2. 性能与成本 ​

2.1 异步上报（默认行为） ​

Langfuse SDK 后台批量发送，不阻塞业务线程。短脚本记得 flush()。

2.2 控制上报量 ​

手段说明
截断大 payloadCC_LANGFUSE_MAX_CHARS=20000
采样只追踪 10% 请求（OTel Sampler 或业务层判断）
过滤无用 Span如 tRPC-Agent 过滤 HTTP 自动埋点
避免逐 token 上报不要每个 stream chunk 建一个 observation

2.3 Token 成本分析 ​

利用 Generation 的 usage_details 在 Dashboard 按模型聚合：

发现：gpt-4o 占 80% 成本，其中 30% 是重复的长 system prompt
行动：Prompt 管理 + 缓存 system prompt

3. 可靠性设计 ​

3.1 fail-open 原则 ​

追踪系统挂了，主业务必须照常运行。

Claude Code Hook 的实现：

python
try:
    from langfuse import Langfuse
except Exception:
    sys.exit(0)  # SDK 不可用 → 静默退出，不报错

# 任何未预期异常
except Exception:
    return 0  # 绝不让 Hook 导致 Claude Code 失败

3.2 可靠投递 ​

Hook 方案中，flush() 成功后才推进 turn_count 和文件 offset：

上报失败 → 下次 Hook 触发时重读同一段 jsonl → 重试上报

生活类比：快递没签收成功，单子不会丢，下次再送。

3.3 进程退出 ​

python
import atexit
atexit.register(lf.flush)

Web 服务通常在 shutdown hook 里调用 lf.shutdown()。

4. 自托管要点 ​

4.1 组件依赖 ​

自托管 Langfuse 通常需要：

  • PostgreSQL（元数据）
  • ClickHouse（追踪数据）
  • Redis（队列）
  • S3/MinIO（可选，媒体存储）

4.2 SDK 版本与 Server 版本 ​

注意 Python SDK 大版本与 Server 版本的兼容性：

  • 本仓库 Claude Code 方案使用 SDK v2（langfuse>=2,<3）
  • 自托管 v3 Server 通常兼容 v2 SDK 的有状态 API
  • 最新 v3/v4 SDK 走 OTel，部分 observation type 在旧版前端可能显示异常

4.3 环境变量 ​

bash
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://your-langfuse.example.com  # 自托管域名

5. 运维检查清单 ​

上线前 ​

  • [ ] 密钥通过环境变量注入，不进代码仓库
  • [ ] 敏感字段脱敏策略已启用
  • [ ] 大 payload 截断阈值已设置
  • [ ] 短生命周期进程有 flush() / atexit
  • [ ] fail-open 已验证（断网时主业务正常）

上线后 ​

  • [ ] Dashboard 能看到 Traces 且延迟合理
  • [ ] Token / Cost 统计符合预期
  • [ ] 无重复 Trace（Hook + Watcher 未同时开）
  • [ ] 定期清理不需要的历史数据（按合规要求）

6. 学习检查 ​

  • [ ] 能列出 3 类不该上报的敏感数据
  • [ ] 理解 fail-open 的设计理由
  • [ ] 知道短脚本和 Web 服务在 flush 上的区别
  • [ ] 了解自托管的基本组件依赖

恭喜 🎉 ​

你已经完成 Langfuse 从 0 到 1 的学习路径。建议下一步：

  1. 继续学习 ../opentelemetry/ 系列，加深追踪基础
  2. 实践 ../../ai/cli/claudecode/langfuse_trace/ 方案
  3. 在自己的 LLM 项目里接入 Langfuse SDK