learnNote

主题

7. 快速上手指南 ​

1. 前置条件 ​

  • Python 3.9+
  • Langfuse 账号（Cloud 或自托管）
  • Claude Code 或 trpc-claudecode 已在使用

2. 安装 ​

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

requirements.txt 内容：

langfuse>=2,<3

3. 配置环境变量 ​

bash
export TRACE_TO_LANGFUSE=true
export CC_LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
export CC_LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx

# 自托管时修改 host
export CC_LANGFUSE_BASE_URL=https://cloud.langfuse.com

建议写入 ~/.bashrc 或 ~/.zshrc。

完整环境变量表 ​

变量必填默认值说明
TRACE_TO_LANGFUSE✅—必须为 true
CC_LANGFUSE_PUBLIC_KEY✅—也可用 LANGFUSE_PUBLIC_KEY
CC_LANGFUSE_SECRET_KEY✅—也可用 LANGFUSE_SECRET_KEY
CC_LANGFUSE_BASE_URLhttps://cloud.langfuse.com也可用 LANGFUSE_BASE_URL
CC_LANGFUSE_DEBUGfalse详细日志
CC_LANGFUSE_MAX_CHARS20000截断阈值
CC_LANGFUSE_REDACTtrue敏感信息脱敏
CC_LANGFUSE_INCLUDE_SUBAGENTStrue子代理嵌套上报
CC_LANGFUSE_SUBAGENT_TIME_WINDOW_S10子代理匹配时间窗
CC_LANGFUSE_STREAMINGtrueWatcher 流式模式
CC_LANGFUSE_WATCH_POLL_S1.0Watcher 轮询间隔
CC_LANGFUSE_WATCH_IDLE_S300空闲停止跟踪秒数

4. 方案选择 ​

方案 A：Watcher（推荐） ​

bash
cd watcher
./run_watcher.sh

或指定 trpc-claudecode 目录：

bash
python3 claude_langfuse_watcher.py \
  --projects-root ~/.trpc-claudecode/projects

然后在 Claude Code 里正常编程，打开 Langfuse UI 即可看到实时 Trace。

方案 B：Hook ​

bash
# 1. 部署脚本
cp hook/langfuse_hook_all_agents.py ~/.claude/hooks/

# 2. 在 ~/.claude/settings.json 注册 Stop Hook
# 详见 langfuse_trace/方案实现说明.md

5. 验证上报成功 ​

5.1 检查日志 ​

bash
# Watcher 日志
tail -f ~/.claude/state/langfuse_watcher.log

# 共享解析日志
tail -f ~/.claude/state/langfuse_hook.log

成功时看到类似：

streaming trace started turn=1 session=b0dcb60c-...
streaming tool started name=Bash id=toolu_01XYZ
streaming turn finalized turn=1 session=b0dcb60c-...

5.2 检查 Langfuse UI ​

  1. 打开 Langfuse Cloud → Traces
  2. 筛选 tags 包含 claude-code
  3. 点开一条 Trace，应看到：
    • 名称 Claude Code - Turn N
    • 树状时间线：Generation + Tool Span
    • Token 用量非零
    • 延迟非 0.00s

5.3 运行端到端测试 ​

bash
# Watcher 测试
cd watcher && ./run_e2e_langfuse_watcher_test.sh

# Hook 测试
cd hook && ./run_e2e_langfuse_test.sh

6. 典型使用场景 ​

场景 1：日常开发可观测 ​

bash
# 终端 1：启动 Watcher
./run_watcher.sh

# 终端 2：正常使用 Claude Code
claude

场景 2：CI 离线分析 ​

bash
python3 claude_langfuse_watcher.py \
  --transcript /path/to/session.jsonl \
  --once

场景 3：调试单个 session ​

bash
export CC_LANGFUSE_DEBUG=true
python3 claude_langfuse_watcher.py \
  --transcript ~/.claude/projects/xxx/session-id.jsonl \
  --poll-interval 0.5

7. 注意事项 ​

  1. Hook 和 Watcher 不要同时开 — 会重复上报
  2. SDK 版本必须是 v2 — pip install 'langfuse>=2,<3'
  3. 短脚本测试记得 flush — Watcher/Hook 内部已处理
  4. 子代理需要 INCLUDE_SUBAGENTS=true — 否则 Agent/Task 内部不可见

8. 目录与状态文件速查 ​

~/.claude/
├── projects/                          # Claude Code transcript
│   └── <hash>/<sessionId>.jsonl
├── hooks/                             # Hook 脚本部署位置
│   └── langfuse_hook_all_agents.py
├── settings.json                      # Hook 注册
└── state/
    ├── langfuse_hook_all_agents_state.json   # Hook 状态
    ├── langfuse_watcher_state.json           # Watcher 状态
    ├── langfuse_hook.log                     # 共享日志
    └── langfuse_watcher.log                  # Watcher 日志

遇到问题 → 8_troubleshooting.md